Since #595 (v0.19.0) a playing preview and Cache Frames When Idle render one frame per
lane, a lane per core, each recording, submitting and reading back a whole frame on the
GPU the window draws with. On a GPU that can't keep up, the window froze for hundreds of
milliseconds to seconds and the playhead jumped ahead when it came back.
Lanes now take a GPU frame only while fewer than a limit of them composite. The limit
starts at one lane and adapts to the window's frame gaps while a preview plays: a stall
(>100 ms) with lanes compositing halves it, half a second of smooth frames (<50 ms) with
every allowed lane busy adds one, up to every lane; a limit that stalled is tried again
only after 10 s. Frames on the CPU (Software Only, no or retired GPU, GPU memory
pressure) and disk-cache hits use every lane; the pool and the viewer's frame are not
limited, and frames ahead of the playhead still start first.
* WebAssembly ABI 2: neighbouring frames for effect plug-ins (#2773)
A wasm plug-in can export ec_api_version 2 and ec_render2 to receive the layer's previous and next frames, their layer times and validity flags. Neighbours come from PluginHost::input_at, are resampled onto the current grid, and are zeroed when absent. ABI 1 modules (ec_render) load and render unchanged; the manifest api stays independent. A layer with an ABI 2 plug-in keys the render cache on layer time; the Plug-in Library accepts ABI 1-2 releases. Docs, help text and tests updated.
* Fix ABI 2 neighbour times on NTSC frame boundaries
ime * fps is often a few ulps off an integer at rates such as 24000/1001. The old boundary test then took the bracket branch and passed the current frame back as prev (or
ext). Treat a near-integer as a frame boundary within 1e-6 frames, and test 2400 frames at 24000/1001: every boundary must get the frames either side. Also document the loader helpers for the docstring coverage check.
---------
Co-authored-by: justanshh <294019246+justanshh@users.noreply.github.com>
* #3099: placed .ai pages fill the size After Effects stored; null anchors default to the corner
Footage of an .aep keeps the size After Effects stored for a placed PDF / Illustrator / EPS
file (the ArtBox, rounded up), and masks and anchors are measured against it. The page was
drawn as a PDF viewer frames it (CropBox, /Rotate) at its own size, scaled by the width ratio
at full resolution and stretched to the stored aspect below 3/4: masks too large, art off
centre, squeezed at half resolution.
- effectcraft-pdf: Framing::Placed / parse_page_framed (ArtBox clipped to the CropBox,
/Rotate ignored); boxes with a non-finite corner or span are not used
- Footage::placed_page (set by the .aep importer, serialized only when true): the page is
framed so and filled into the stored size (effectcraft_render::vector_fit), decoded,
continuously rasterised and in Create Shapes from Vector Layer; Reload keeps the size;
the frame cache keys it by size and framing
- .aep import/export: a null's absent Anchor Point is [0, 0], as After Effects reads it
- fixture ai-mask-3099.aep (own synthetic files, scrubbed, profiles stubbed) and tests
against After Effects 2026's read-back
* #3099: placed-page framing only for .ai and .pdf, EPS as before; doc comments
After Effects' sizing was measured with PDFs named .ai only; an EPS from an .aep keeps its
bounding box at its own size (listed as not measured in docs/gaps.md and docs/aep-import.md).
Doc comments on the touched functions.
* #3099: shapes from a placed page keep its frame (track matte)
Create Shapes from Vector Layer converted every path of a placed page, so bleed, art past the
artboard or the page's background showed where the footage's raster hides them. The layers it
makes from a placed page now take a hidden "<layer> Frame" shape layer (the footage's
width x height) as their Alpha track matte: drawn at the comp's resolution, its edge is the
raster's on shape and image layers alike. The command returns the frame layer's id too.
Related to #1365. Display labels only; effect, command, parameter, panel and serialized ids and the AEP/script match-name tables are unchanged.
- 69 Cycore CC effects, Key Light, Mocha shape, Lumetri Color/Scopes and the Mercury renderer labels get descriptive names; the old names stay case-insensitive lookup and search aliases.
- Backend::parse accepts the new renderer labels, so reported settings round-trip.
- Display names are unique per language in every effect catalog (new test).
- Warp Stabilizer and Roto Brush keep their names until RFC-0029 settles.
- Mapping in docs/feature-naming.md.
The matte (or the Colors display's pixels) is made from the unscaled ID and coverage channels at source resolution, box-filtered below render scale 1, kept per footage frame, layer, selection, output and scale in a cache in the common memory budget, and uploaded to the GPU as one R32F plane. OpenEXR file identity checks are remembered for 1 s; Reload Footage forgets them.
- Value decays by ln(seconds unused + 1) + 1 instead of halving every 30 s.
- Each balance reads the process's resident memory (memory-stats, at most every 250 ms): over
95 % of the RAM left after the reserve the caches give way by what it is over; what they
freed for it counts as freed; over all of it also protected preview frames go.
- Frames a playing preview shows next go last and may keep the caches over the budget by a
tenth of it (at most 1 GB).
- Frames and plane sets go to the disk cache only when making them again costs more than
reading them back (measured read rate, 10 ms per MB until measured).
- At most 256 movie/audio files stay open (least recently used idle one closed).
The panel worked a thumbnail's key out again only on a new project revision, footage reload or time, but Switches Affect Nested Comps and real-time shadows change what a comp shows without either: the preferences revision is now part of the check. The docs say the browser's Footage Frame Cache is at most 256 MB for frames and channels together. The panel test changes the preference alone; it fails on the old code.
An animation preset applied keys or an expression to a channel selection: its effect groups now go through static_channel_params and a lone property takes the preset's first value (said in a toast and the reply). Add Expression on a selection failed and rolled back as a whole when a channel selection was selected: it is now left out, as Add Keyframe leaves it out (named alone it is still an error). upgrade_effects is #[must_use]; File > Import Project adds what lost its animation to its warnings, a template keeps it quiet (it is read for listings and thumbnails too). Tests for the preset, the selection and the import; each fails on the old code.
Adopting a new folder's copies runs outside the localizer's lock, so the worker could start a copy meanwhile: the scan could delete its temporary or take its copy, counting it twice. The worker starts no copy while a folder is adopted (ended by a guard, also on a panic), the scan leaves the files of a copy already running alone, an adopted entry never replaces one made meanwhile, a copy of an earlier setting is not deleted when the adoption took it, and a failed copy of an earlier setting doesn't mark the file skipped. A test holds a folder's adoption, asks for a file meanwhile and checks no copy starts and it is counted once; it fails on the old code.
A remembered failure refused any later request for 'all channels', but those are every channel but the picture's: a picture too large to read left the file's other channels unread. A failure now refuses a request only when it asks for everything the failed one did. The browser's plane cap is 256 MB, the browser's largest footage budget (frames and planes together). A test fails a picture read and then reads the other channels; it fails on the old code.
set_budget during a running balance was skipped (the running pass kept the old budget);
balance() now marks a request the lock holder runs again, also when note_growth held the lock.
A poisoned balancing lock is taken over instead of counting as busy forever.
prop.setExpression refused only a non-empty text on a property that can't be animated, but a call without text (a toggle) or with enabled: true adds the default expression, and pasting expressions (Copy Expression Only) set them too. Every call that would add, switch on or change an expression on such a property is now refused, switching an old one off or removing it still works, and a pasted expression skips such properties. Tests: both bypass forms are refused (they fail on the old code); an old expression can be switched off and removed but not on again.
After Effects 2026 reports ID Matte's Use Coverage as able to vary over time and take an expression (Aux. Channel and 3D Channel Extract's 3D Channel can't), so it is animatable again. ID Matte now reads the coverage channel whether Use Coverage is on or off: what a frame reads still doesn't depend on a value that moves. A test checks the need is the same both ways and which ID Matte parameters are static.
Setting the localizer adopted a folder's copies (reading the folder and every record, deleting temporaries) while holding the localizer's lock, which every footage read takes to look for a copy; dropping copies over the limit and checking a copy's size did file work under it too. The folder is now read, the free space taken and copies checked and deleted without the lock; the lock only guards the bookkeeping, and a setting changed meanwhile wins.
The plane store remembered failed requests (unreadable, too large) by what they asked for alone: a file replaced on disk without Reload Footage got a new index but kept being refused, so its channels stayed missing and its picture fell back to a whole-file decode every frame. A failure now keeps the index it was made with and only refuses requests of that index; a failure of the new file replaces the old ones. A test fails a broken file, then reads its fixed version under a new index; it fails on the old code.
MediaPool::aux (no render asks for it: renders ask for what their effects read) again gives every channel, the picture's too, so the pinned OpenEXR golden hashes stay as they were; 'all channels' without the picture applies to the effects' requests. docs/effects.md is generated: the note on static channel selection lives in docs/footage.md.
The cancellable footage view passed aux and aux_for straight to the source, so a viewer render called off during a channel decode kept decoding. They now go through the render's cancel flag like frame reads (a decode stops between batches; once called off none starts). A test checks a channel read runs under the flag and none starts after; it fails on the old code.
The Layer Cache, Footage Frame Cache and Preview (RAM) Cache settings are gone. The big caches
(layers, footage frames, OpenEXR planes, preview frames, the disk write queue) share one budget:
80 % of the installed RAM left after the reserve (5 GB while RAM is unknown, 3.5 GB in the
browser, at least 192 MB). No cache has a share of its own; the memory accountant frees the
least valuable item first across all of them: cost to make again per byte, decayed by time
unused, a copy worth nothing, a thrashing cache protected. Host sessions (CLI, MCP) apply the
budget from the start. Low-memory halving holds until twice the threshold is available again,
with one toast per episode. Saved settings lose the three old keys and keep the reserve.
The parameters that pick which channels or Cryptomatte layer an effect reads (EXtractoR's Red/Green/Blue/Alpha, Cryptomatte's Layer and Layer Name, 3D Channel Extract's 3D Channel, ID Matte's Aux. Channel and Use Coverage, IDentifier's Channel Type) are static, as in After Effects where they have no stopwatch: no keyframes, no expression (prop.addKey, prop.toggleKey, prop.toggleAnimation and prop.setExpression refuse; prop.set changes the value). A document or an import that animated one keeps its first value and says so (a toast on open, a loss on .aep import). With that, what a frame reads is known from the values alone: the 'all channels' fallbacks for moving parameters and for effects that don't declare are gone (every channel effect declares; a test holds them to it), and a layer whose effects read no channels asks for none. Tests: the parameters refuse keys and expressions and the need is exactly the channel picked; a keyed channel selection opens static with its first value and is reported (both fail on the old code); the migration keeps the first key's value.
The plane store kept the R, G, B, A planes a picture was made of whenever the picture was read with channels for its effects (or with all of them), beside the converted picture in the media pool's frame cache: the same pixels twice. Once the picture is converted, its planes now leave the stored set (in place when nobody else holds it), but for a picture channel an effect names itself (EXtractoR reading R). 'All channels' means every channel but the picture's. A test reads a picture with one channel, with a named picture channel and with all channels, and checks exactly what stays and its bytes; it fails on the old code.
The plane store had a fixed 1 GB budget of its own, outside the preferences: with a Footage Frame Cache of 10000 MB it still held about 2.5 frames of a 69-channel 1080p file. The plane store and the media pool's frame cache now share the Footage Frame Cache (set_cache_budget sizes both and the memory accountant's footage group), with one least-recently-used order: each use takes a stamp from one shared counter, and over the footage budget the accountant drops the least recently used item, frame or plane set, whichever holder keeps it. Neither side has a share of its own. The common budget no longer adds a separate plane budget; the browser keeps its 512 MB cap on the planes. Tests: a footage budget of 10000 MB sizes the plane store (and resizes it at run time); filling the frame cache drops the oldest plane sets and filling the plane store drops the oldest frames (fails without the shared order: the frames went first); an accountant group shares its budget.
A drop guard takes the copy hook out and turns the localizer off at the end of the test that installs the hook, also when an assertion fails, so a later test doesn't inherit a hook that holds its copies.