Assembling

▶Video tutorial — coming soon

Assemble is the one destructive verb in OSA. Everything before it is a plan; this is the moment the plan becomes a Harmony scene.

What it does

In one pass, walking the staging tree:

1. Creates the nodes — pegs, groups, composites, backdrops, reads, effects, generators.
2. Connects the ports — the green transform hierarchy and the blue composite hierarchy, both.
3. Writes the attributes — composite modes, alignment, alpha, blend modes, effect values, z-depths.
4. Imports the artwork — into elements and exposures, art layer by art layer, frame by frame.
5. Lays the graph out — the Wide Bus grid, with backdrops measured from the inside out.
6. Flattens the stacks — rewrites the staging tree into the shape the scene can actually store (see Original Bitmap).

Before you press it

The Assemble button lives at the bottom right, beside Cancel, and it is gated: when the feedback bar is showing a blocking error, the button is disabled. OSA will not let you assemble a tree it knows is wrong.

The feedback bar above it carries the blocking reasons in colour, so the answer to "why is the button grey?" is always on screen.

The report

Assemble reports what the scene refused, not what it did. A report that shouts on every build is background noise, so the distinction is deliberate:

Mark	Meaning
FALHA (failure)	something was asked for and did not happen
nota (note)	it happened, just not the way it was asked

Each line names the kind, the subject and where it happened:

FALHA import-failed   sky: source file not found [Top/BG/sky]
nota  degraded        can: vector track skipped in Original Bitmap

The full vocabulary is closed — every failure has one of these kinds:

Kind	Means
no-bridge	Harmony is there and the script bridge never opened
import-failed	the artwork never reached disk
no-artwork	there was nothing to carry (a note)
element-swap	an Original Bitmap drawing stayed a TVG
unresolved	no column or element for the node
drawing-failed	Drawing.create was refused
exposure-failed	column.setEntry was refused
utransform	a conversion was refused or produced nothing
node-failed	node creation was refused
plan-error	an exception while committing one plan
phase-error	an exception in a whole phase
format-mismatch	the extension lies about the file's content
degraded	done, but not as asked (a note)
cancelled	you interrupted the build
unaddressable	a node claims to exist but cannot say where

Cancelling

Cancel stops the build. It does not undo what was already written.

Assemble is not a transaction

Harmony's undo accumulates the whole build into a single write, so cancelling halfway leaves the nodes that were already created. That is a property of the host, not a choice — and it is why the flatten step only touches drawings whose sources actually landed: after a cancel, your staging tree still describes everything that did not make it.

If a build goes wrong, the honest recovery is Harmony's own undo, then fix the tree and assemble again.

Re-assembling

You can assemble the same tree again. Nodes that already exist in the scene are edited where they are — renamed, re-attributed, never duplicated and never moved — and the slot is marked existing again afterwards, so the next press is another update.

A node that says it exists but cannot say where is reported as unaddressable rather than being rebuilt, because rebuilding it would mean two of them.

There is a whole page on this, including why the root of the tree is not Top for an imported chain: Re-editing an Assembled Scene.

Generate + Assemble

The Generate Magnet Tree + Assemble button in the Staging toolbar does both steps in one press: it creates one super node per active magnet and assembles them straight into the Node View.

It is standalone — no artwork, no staging, nothing dragged in. On an empty scene it builds the destination hierarchy on its own, which is how you hand a rigged empty scene to whoever starts the shot.

What it builds comes from the Magnet Generator recipe of the active Preference Set: which magnets exist, which are active, their order, the components each one is born with, and its backdrop colour. Switching preference sets switches the whole result, so check the combo in the top bar first. See Magnets.

After the build

The staging tree is rewritten to match the scene: stacks flatten, tracks that landed collapse into their layer, and each flattened row keeps its provenance — where the artwork came from, its type, its thumbnail.

The slot goes on accepting new tracks afterwards. The flat is not the end, it is the base: the next composition composes on top of what is now in the scene.