Skip to content

Layers LA7a: the delivery and words guides teach the layered exports - #172

Open
wackyza wants to merge 9 commits into
shinyobjectz:mainfrom
wackyza:layers-skills
Open

wackyza wants to merge 9 commits into
shinyobjectz:mainfrom
wackyza:layers-skills

Conversation

@wackyza

@wackyza wackyza commented Nov 17, 2026 •

Copy link
Copy Markdown

Stacked on #167, #170 and #171; review the top commit, ee345171. Goes with shinyobjectz/raea-skills#99.

  • motion/delivery: a cut an editor finishes goes out in layers (raea export capcut, raea export xml with an XML
    for each editor); what arrives; that captions and graphics are pictures in the editor, so a word is fixed in raea
    and exported again; and what to pass on from the notes — CapCut's crop that can't change over a clip first.
  • motion/words: mark captions data-raea-role="caption", in its example too.
  • The skills submodule points at the raea-skills PR's commit (27175db, on wackyza/raea-skills); once that merges,
    the pointer moves to its merge commit. tools/skills.sh check-cli passes against this tree's raea.

🤖 Generated with Claude Code

…the only layer split out of it

docs/layers.feature after working through the implementation:
- Text is part of the graphics layer. Pulling words apart from the graphics they're built into (kinetic type, words
  cut from a shape, a word behind a graphic) caused more problems than it solved; a text layer may come later, opt-in
  only (an element marked data-raea-role="text"), never guessed.
- Captions are the only layer split from the graphics: marked data-raea-role="caption", nothing guessed.
- One `raea export xml` for Premiere and Resolve; a command of an editor's own only if testing finds it reads the XML
  differently.
- Leaner: the layers composited back is a test of the method, not run on every export; an export always renders its
  own reference; no `raea check` heuristic for unmarked captions; no moving covered captions (captions go on top).
- What rendering the passes taught: the page keeps only the data-raea- props it names, it draws nothing inside a
  hidden element (so the captions pass clears what holds a caption), and 3D is Bevy's, so a layer without it leaves
  the 3D out of the scene and keeps its cameras.

Spec only; no code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zachary Guglin and others added 8 commits November 17, 2026 14:58
…YER renders one layer of an export (captions, graphics, under)

docs/layers.feature amended: text is part of the graphics layer (a text layer only ever opt-in), one `raea export xml`
for Premiere and Resolve, the composite check a test of the method rather than every export's, no reuse of an earlier
render, no unmarked-caption heuristic.

- sdk/timeline: the captions operation's `text` ops say `caption: true`, as does a caption clip added on its own
  (said: true), so the code raea-feed writes can carry the mark.
- runtime/page elements.rs: data-raea-role is kept on the page (KEPT names the data-raea- props the page keeps; the
  mark was dropped before it could be matched).
- systems/layers hide.rs: RAEA_LAYER=captions draws only what is marked a caption: the page draws nothing inside a
  hidden element (vendor/blitz-paint render.rs), so what holds a caption is cleared, not hidden, as RAEA_HIDE_MEDIA=under
  clears what holds footage. graphics and under are RAEA_HIDE_MEDIA's 1 and under, less the captions. RAEA_HIDE_MEDIA's
  own CSS is unchanged, so raea export capcut is too. hiding_css is the pure function hidden_css reads the settings into.
- runtime/scene items_of: a layer that draws no 3D (captions, under; raea_sys_layers::draws_3d) keeps only the
  cameras, since Bevy draws the 3D and the page's CSS can't hide it. This also keeps the 3D out of capcut's under pass
  once it moves onto RAEA_LAYER.
- runtime/bundle cache.rs: a render with RAEA_LAYER isn't the export cache's, as with RAEA_HIDE_MEDIA.

Checked with a source build on two fixtures (footage on a card, a lower third and a caption with a highlighted word;
a 3D turntable with a title and a caption): each layer draws only its own, and raea export capcut writes its draft
as before. Tests: raea-sys-layers, raea-runtime-scene, raea-runtime-page, raea-runtime-bundle, sdk/timeline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ayers.json; the 3D is the layer under the page

- apps/layers (new): `raea export layers EDIT.tsx [-o DIR]` renders the reference with its manifest, then the
  graphics, under (when there's footage or 3D) and captions (when a frame shows one) passes; writes each layer's
  movie, layers.json (model.rs: the editor-neutral timeline, tracks top to bottom, footage linked to its own sound),
  NAME.srt (srt.rs) and reference.mp4. The manifest's readers (runs, sounds, spans, full, resolve) move here from
  apps/capcut/src/plan.rs; CapCut keeps its own placement and track laying and reads the rest from here.
- engine/page manifest.rs: a text entry inside data-raea-role="caption" says caption: true (the SRT's words, and
  whether the captions pass runs). runtime/export: the manifest says has3d.
- The 3D moves from the graphics layer to the one under the page (raea_sys_layers::draws_3d): raea draws the 3D first
  and the whole page over it, footage included. The under pass renders opaque, since --alpha clears the 3D's clear
  colour, which is the page's background over 3D (three-d lost its background: 21 dB before, 39 after).
- vendor/blitz-dom mutator.rs: an element whose :has() was matched (ANCHORS_RELATIVE_SELECTOR) is matched again when a
  node under it is inserted or removed, as Chrome does. A caption a <Sequence> put on the page at frame 10 stayed
  hidden under the captions pass's :not(:has(...)) (lower-third: 23.5 dB before, 34.1 after); footage coming in
  later under RAEA_HIDE_MEDIA=under had the same fault. Recorded in vendor/vendor.toml.
- apps/layers composite.rs (LA3a), an ignored test run by hand with a GPU: four fixtures (apps/layers/fixtures)
  exported, composited back bottom to top at each clip's first, middle and last frame, against the reference:
  highlight 33.0-35.1 dB, lower-third 34.1-35.1, pip-card 33.2-33.5, three-d 39.1-39.8 (floor 30).
- docs/layers.feature brought up to what was built; docs/manual/reference/cli/export.md regenerated
  (tools/manual-ref.sh gen). The skill's reference/cli.md (raea-skills) needs the new verb with LA7.

Tests: raea-app-layers, raea-app-capcut, raea-sys-layers, raea-runtime-scene, raea-runtime-page, raea-runtime-bundle,
blitz-dom, raea-cli (with the skills submodule), sdk/timeline; tools/layers.sh. raea export capcut runs as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… captions track and the reference in the draft

- apps/capcut exports the composition in layers first (raea_app_layers::export into out/capcut/NAME: the reference,
  the graphics, under and captions passes, layers.json) and writes layers.json as CapCut's tracks (from_layers.rs,
  pure): bottom first, the footage CapCut's main track, "raea overlay" (the graphics) above it, "raea captions" above
  that, "raea under" below the footage when there is one. A footage clip's linked sound is its volume, as CapCut keeps
  a video's own sound (Extract audio separates it); footage with no linked sound is silent.
- The reference render is copied into the draft's folder, on no track (where CC2d kept it only beside the draft).
- The export's own three renders, its overlay and under spans, its footage-covered check and its media probes go:
  raea-app-layers does them, for every editor. CapCut keeps where a picture sits in its terms (plan::place) and the
  draft's cover. The manifest readers' tests move to raea-app-layers with the code; `lay` goes (model::lay).
- What changes for a composition with no captions: the 3D is under the footage, as raea draws it, not over it.

Checked: lower-third and three-d (apps/layers/fixtures) exported as drafts with -o: footage, raea overlay, raea
captions (frames 10-50) / raea under, raea overlay, raea captions; reference.mp4 in each draft folder. Tests:
raea-app-capcut (with a layers.json-to-tracks test), raea-app-layers; tools/layers.sh; manual regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ween it and the footage under it

A picture in picture on a card over footage that fills the frame lost its card: the card is a background holding
footage, so it went into the under layer, beneath every piece of footage, where the full-frame clip covers it (the
multi-clip test's C in the corner over B at 4-6 s: 23.2 dB). CapCut's export always had this.

- systems/layers hide.rs: RAEA_LAYER=behind:FILE draws the backgrounds of what holds FILE and no other footage; what
  holds other footage too is cleared, not hidden (the page draws nothing inside a hidden element); the rest hidden.
- apps/layers: a behind:FILE pass for each file shown as a picture in picture, its clips kept only where it is one, on
  a "behind picture in picture" track (Layer::Backing) between the pictures in picture and the footage that fills the
  frame. CapCut names it "raea behind picture in picture".
- composite.rs finds a layer's frames by its movie's name (several backing passes), and RAEA_LAYERS_PROJECT checks a
  project of its own: the multi-clip test passes at 36.2-42.7 dB (37.5-38.3 in the picture in picture); the fixtures
  still pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e Pro and DaVinci Resolve (work in progress)

- apps/layers xml.rs (pure): layers.json as xmeml version 5: one sequence at the composition's rate (29.97 as 30 NTSC)
  and size; video tracks bottom first; footage at its file where it is, placed by Basic Motion (scale, centre in frame
  units), a Crop where object-fit: cover cuts it, its Opacity; the layers' movies full frame, alpha straight; Audio
  Levels as linear gain; a footage clip linked to its own sound.
- Sound laid out as Premiere Pro 2026 writes it, read from an XML it exported: the sequence explodedTracks, each
  stereo file's channels described one by one, each channel a mono clipitem on a track of its own (sourcetrack and
  outputchannelindex 1 and 2), every clipitem of a clip and its linked clip linked together, a masterclipid each, and a
  timecode on every file. The first layout (one stereo clipitem on a "Stereo" track) imported with no audio at all.
- File gains channels and sample_rate (layers.json reads files without them as stereo at 48 kHz).
- `raea export xml EDIT.tsx [-o DIR]`: the layers into out/xml/NAME, NAME.xml beside them; in raea's help and the
  manual.

Checked so far: the multi-clip test imports into Premiere Pro 2026 with its video and, after the layout above, its
sound. Still to check: placement, transparency and Unlink in Premiere; all of it in Resolve.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…esolve as raea rendered it, stereo kept

- Each channel of a stereo file is panned to its side by FCP7's Audio Pan on its clip (-1 left, 1 right), as Resolve
  writes it. Without it Premiere and Resolve both imported the channels centred, so a stereo track played as mono
  (heard with a raea-rendered track, a low note left and a high note right). Premiere's own track pan
  (PannerCurrentValue) was tried alongside it and neither editor read it, so it isn't written.
- Sequence explodedTracks, a timecode on every file and a uuid, as Premiere writes them: without them Premiere
  imported the mono-a-channel sound as an empty A1.
- docs/layers.feature: LA5a's sound layout and pan; LA5b's results on 11-16 (Premiere Pro 26.2.2, DaVinci Resolve
  21.2.0: the multi-clip test with every track, clip, source time, placement and caption as raea rendered it, nothing
  offline, ProRes 4444 transparent, footage sound linked, music stereo); LA5c, CapCut 9.4.4589 opening the drafts
  (CC3a). No editor needs an XML of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… in every export, each editor placing it as raea drew it

The manifest says what of a video a box it's in leaves showing (clip) and its object-position; layers.json keeps
each footage clip's box, clip, object-position and opacity at the frames they change (keys). One reading of a
picture (plan::picture: object-fit, object-position, cut only where its box or a box it's in cuts it inside the
frame) places it in every export:
- the FCP7 XML keyframes Basic Motion, crop and opacity, written per editor (NAME.premiere.xml, NAME.resolve.xml):
  Premiere's crop in Basic Motion, Resolve's as FCP7's Crop mirrored for a phone's take stored turned; Scale and
  Center each in that editor's clip at Scale 100 (Premiere: the media as described, a phone's take as stored;
  Resolve: the media fitted to the timeline), read from what each did with what it was given
- the CapCut draft keys position, scale and opacity (common_keyframes); its crop holds as the first frame shows it,
  and a crop that changes over the clip (a split screen's seam) is said: CapCut can't show it
- keys a straight line between gives to 0.15 px are left out; a clip at another speed is placed at its own, and said

Also: a layer's ProRes movie that opens on an opaque frame keeps one sample description with alpha (VideoToolbox
otherwise starts a second, which Premiere won't import and Resolve shows opaque); a sound's clip ends where its file
does; the stack's duplicate code folded (tools/dupes.max 59 -> 58 near).

Checked on 11-17: Premiere Pro 26.2.2 and DaVinci Resolve 21.2.0 on the Telluride test (iPhone takes, a keyframed
split close) and the positioning test (horizontal and phone takes, 1080 and 4K compositions); CapCut 9.5 on Telluride;
LA3a composites the fixtures and the positioning test back as the render at 33-49 dB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… skills pinned at the raea-skills layers-exports branch

motion/delivery says a cut an editor finishes goes out in layers: `raea export capcut` (or the app's Export to,
then CapCut) and `raea export xml`, its NAME.premiere.xml and NAME.resolve.xml each for its own editor; what arrives
(footage and sounds as clips of their files, keyed where they move, raea's drawing as transparent clips over and
under them, captions on their own track with an .srt, reference.mp4 to compare); that captions and graphics are
pictures there, so a word is fixed in raea and exported again; and what to pass on from the notes, CapCut's crop
that can't change over a clip first. motion/words says to mark captions data-raea-role="caption", in its example
too. The skill's copies and reference/cli.md (now listing raea export layers and raea export xml) are regenerated in
raea-skills; tools/skills.sh check-cli passes against this tree's raea.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant