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.
Session::thumbnail_key: a comp's content key (as the disk cache keys frames), footage's item and
settings, the time, the size, the render switches and the footage reloads so far. The panel
renders a thumbnail again only when that key changes, not on every revision.
- A covered batch is served before a remembered failure; failures are kept per request, so a
broken part or too many channels never hides the picture; a picture too large with its
effects' channels is read alone.
- Hostile headers: parts whose data window or uncompressed block is out of bounds are refused
before any decoder sees them (index, reader and the image crate's whole-file path, import).
- Seek and read errors are transient (Stopped), not remembered; the copy path notes its file.
- The index drops the headers' other attributes and previews, is bounded by bytes and checks
the file's identity before it is reused.
- A picture read alone isn't kept twice (plane store and frame cache).
- A waiter whose decodes keep being called off decodes a copy; rounds are bounded.
- The Cryptomatte probe asks with its own effect's need; animated parameters are found in
nested groups.
- Test hooks and caps are keyed by path; new tests: data window offsets, failures per request,
too large with channels, the file bound, hostile data windows, damaged files, rows and levels
on every compression and on tiles.
FootageSource gains aux_for (only what a need reads), aux_names (names from the headers) and
set_aux_needs (per footage file, what its effects read, so the picture is decoded with those
channels in one pass); the wrappers forward them. The renderer asks for the union of the layer's
effects' needs; the engine sends each aux footage's needs with the aux footage set (all channels
when a parameter is animated or an effect doesn't say); layer.channels and the popups read names
only.
Part of #3184 (step 3 of 4).
Layer buffers on disk (and in the browser's layer store) now carry the
files they were made of, like frame entries since step 2, and are checked
against exactly those files when used. The project-wide footage salt is
gone: nothing stamps every footage file any more.
- Layer entry format 4: the buffer's EntryFiles, then the pixels. A hit
checks only the listed files (metadata, or the VirtualFileId hook for
files from memory; Missing must still be missing); a change, a damaged
entry or the old format 0 is a miss and the entry is deleted, so the
re-rendered buffer replaces it. A hit reports its file list, so frames
made of buffers from disk are complete and get stored again.
- Buffers whose files can't all be named are not written.
- Layer disk keys: layer_disk_key = hash of the layer entry version, the
renderer version and the layer cache key (which names the footage items
with their paths and settings, from memory).
- PrefetchStore checks on use; an entry made of changed files is dropped
and forgotten, so the new buffer is queued over it. FrameServer passes
its virtual-file hook to its layer cache.
- Removed: footage_salt(_with), file_stamp, footage_stamp,
set_disk_salt, set_store_salt, Session::refresh_disk_salt,
poll_disk_salt, footage_fingerprint, disk_salt, disk_salt_background,
disk_salt_job, DiskSaltJob, the UI's per-frame poll, the salt in
FrameServer and in the availability worker (with its cache_enabled
plumbing). The disk cache is attached as soon as it is configured.
- Docs: architecture.md, web.md.
Tests: layer entries check their files (size, time, missing/back,
folder, damaged, old format, incomplete); virtual files; prefetch store;
media tests with a real pool across restarts (only the changed file is
read, projects with the same item ids never share an entry, missing,
unreadable and damaged never serve stale buffers); engine tests that the
cache is attached at once and edits do no file work (#1926, #3106).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Disk cache: stamp footage files for the salt off the UI thread
Importing an After Effects project whose footage includes long image
sequences on a network share froze the desktop app for 15-27 s. The
import itself takes about 0.25 s; the time went into the edit's bump(),
where refresh_disk_salt() stats every footage file (13,466 sequence
frames in the measured project, ~15 s) on the UI thread whenever a disk
cache is attached. File > Open and footage reload hit the same path.
With Session::disk_salt_background (set by the desktop app) the salt is
taken on a worker thread and picked up by poll_disk_salt() from the UI
tick. Until it lands the layer cache runs memory-only, so keys under the
old salt (other files, or another project's items) are never read. A
newer footage change supersedes a salt still being taken. Headless
sessions keep taking it synchronously.
A settings change that keeps the disk cache folder no longer re-stamps
every footage file either.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Disk cache: opening a project drops the footage salt being taken
A salt job still running for the old project was kept when the new project named the
same footage, so the salt stamped before the files changed stayed in use.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Session::crypto_coverage returns the coverage of one Cryptomatte ID over the layer, read from
the probe Session::crypto_probe_job keeps: at most max_side samples on the long side, each at
the centre of its cell, or None until the probe is built. It is what the Cryptomatte
eyedropper's hover highlight will draw.
Tests cover the coverage of an ID from the kept probe and the cost of a highlight with six
ranks.
The pool learned that an effect reads a footage item's channels only at the
first aux() call, so the first frame was decoded twice (picture, then in
full), and the hint was never cleared after the effect was removed.
The session now gives the footage source the whole set of files read by
enabled 3D Channel effects (FootageSource::set_aux_footage) with every
project change (Session::bump: edits, undo, redo, history jumps, rollbacks,
project open), sending it only when it changed. The pool keeps that set and,
as a safety net, what aux() learns; a new set drops what was learned.
Refs #474
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve the Interpret Footage form against main's split into
interpret_footage_form and project_settings_form, keeping the Cineon
Settings fields and the pointUnits readback. Restore the Arc, rayon
prelude and cineon_frame imports that main's explicit use lists dropped.
effect.cryptomatteAt rendered the effect's input on every call to learn its pixel grid (up
to ~1 s per hover on a 3D precomp). The aux channels and that grid are now kept in a
CryptoProbe on the Session, keyed by the project revision, layer, effect, frame, scale and
render prefs (nested switches, draft shadows). On footage with nothing animated before the
Cryptomatte effect the frame is the source frame, so a still or a held frame keeps one
probe for every comp time. The effect's own Selection doesn't count: the probe never reads
it, so an animated Selection keeps the probe too.
Session::crypto_probe_ready says whether a query answers from the kept probe and changes
nothing. Session::crypto_probe_job builds it on another thread for the viewer; asking for a
job is starting it. Each started job has a generation: it stores its result only while it
is the newest, a newer job or an edit cancels it, and a panic in the build becomes the
probe's error. A cancelled build checks its generation between its stages (reading the IDs,
rendering the effect's input), so it stops early and lets go of what it read. `probeOnly`
makes cryptomatteAt / pickCryptomatte answer {pending} instead of building on the caller.
A pick re-keys the probe (it only edits the Selection), and undo, redo and history jumps
over picks keep it too (each pick is labelled "Pick Cryptomatte"). Any other edit, footage
changes, Open / New and Session::drop_crypto_probe (the eyedropper disarmed) let it go. The
slot's type is crate-private (the Session field stays public, doc(hidden), so other crates
can still build a Session); crypto_probe_stats and crypto_probe_jobs (jobs run, cancelled
ones included) are doc(hidden), for tests.