cycle-atlas/.agents/skills/after-effects/references/project-hygiene.md

Project Hygiene — Organize, Relink, ExtendScript

Keep AE projects organized, portable, and automatable: consistent naming, a clear folder/bin structure, label discipline, pre-comp discipline, reliable relinking when files move, and ExtendScript (.jsx) automation for repetitive tasks.

Folder (bin) structure

Create folders in the Project panel (the folder icon at the bottom). A reliable layout:

01_Comps/         finished/active compositions
02_Precomps/      nested precomps
03_Footage/       imported video
04_Images/        stills, logos, textures
05_Audio/
06_Solids/        (AE's auto "Solids" folder — keep it here)
07_Assets_3D/
99_Old/           deprecated comps/layers, not deleted yet

Numeric prefixes force a stable sort order. After importing, immediately drag items into the right bin — File > Reduce Project and File > Consolidate All Footage help later, but discipline up front prevents chaos.

Naming conventions

• Comps: PROJECT_section_descriptor_v01 (e.g., BRAND_intro_logoBuild_v03). Version with zero-padded v01, v02.
• Precomps: prefix PRE_ or suffix _pre so they're obvious in lists.
• Layers: rename solids/nulls to their role (CTRL_master, BG_gradient, MATTE_text). Never ship "Black Solid 12".
• No spaces / special chars in filenames destined for render farms or cross-OS sharing — use _ and -.
• Keep names short but unique; long names truncate in the timeline.

Label colors

Use the Label color (the swatch left of each Project/Timeline item) as a visual system. Pick a convention and apply it consistently, e.g.:

• Red = control/null layers
• Blue = footage
• Green = precomps
• Yellow = text
• Purple = adjustment/effects layers

Right-click an item → Label to set. Select multiple, then Edit > Label > Select Label Group to act on a whole color at once. Customize label names/colors in Preferences > Labels.

Pre-comp discipline

• Pre-compose (Layer > Pre-compose, Ctrl/Cmd+Shift+C) to group related layers and to apply one effect to a group — not reflexively for everything.
• When pre-composing a single layer, choose "Leave all attributes in" vs "Move all attributes into the new composition" deliberately: "Move" carries transforms/effects inside; "Leave" keeps them on the outer layer.
• Name the precomp immediately and file it in 02_Precomps.
• Avoid deep nesting beyond a few levels — it slows navigation and makes relinking/debugging painful.
• Match precomp duration and frame rate to need; an over-long precomp wastes cache.

The "moved one file and everything broke" rescue

AE references footage by file path. Moving, renaming, or sending a project without its assets breaks links (shown as colored bars / "Missing Footage" placeholders).

Fix options, in order

1. Relink one, fix many: double-click a missing item (or right-click → Replace Footage > File). Point it at the moved file; AE offers to relink all missing items from the same folder automatically. This single step usually fixes the whole project.
2. Find Missing Footage: File > Dependencies > Find Missing Footage lists every broken link to resolve.
3. Replace Footage: right-click footage → Replace Footage > File to swap an asset while keeping every use, effect, and keyframe intact.

Prevent it: Collect Files

Before moving or sharing a project, use File > Dependencies > Collect Files. This copies the project plus every used asset into one new folder with relative structure, so links survive on any machine. Always hand off projects as a Collect Files package, not a bare .aep.

Related: File > Dependencies > Consolidate All Footage (merge duplicate imports), Remove Unused Footage, and Reduce Project (strip everything not used by selected comps) to slim a project before collecting.

Batch automation with ExtendScript (.jsx)

AE scripts (ExtendScript / JSX) automate repetitive work. Run via File > Scripts > Run Script File..., or place in the ScriptUI Panels folder to dock as a panel. Always wrap edits in app.beginUndoGroup("name") ... app.endUndoGroup() so one Undo reverts the whole batch.

Common automations (full code in ../scripts/):

• Batch rename selected layers with a base name + auto-increment (../scripts/batch-rename.jsx).
• Sequential offset — stagger selected layers in time by N frames each, a staggered "domino" start (../scripts/sequential-offset.jsx).
• Apply an effect (e.g., a Gaussian Blur, or any matchName) across all selected layers at once (../scripts/apply-effect-to-layers.jsx).

Minimal pattern:

app.beginUndoGroup("My Batch Op");
var comp = app.project.activeItem;
if (comp && comp instanceof CompItem) {
  var sel = comp.selectedLayers;
  for (var i = 0; i < sel.length; i++) {
    // operate on sel[i]
  }
}
app.endUndoGroup();

Quick reference

Task	How
New bin	Folder icon at bottom of Project panel
Set label color	Right-click item → Label
Relink missing footage	Double-click item / Replace Footage > File
List broken links	File > Dependencies > Find Missing Footage
Package for handoff	File > Dependencies > Collect Files
Swap an asset everywhere	Replace Footage > File
Slim project	Reduce Project / Remove Unused Footage
Run a script	File > Scripts > Run Script File...
Pre-compose	Layer > Pre-compose (Ctrl/Cmd+Shift+C)

Gotchas

• Collect Files before moving anything. Moving the .aep alone always breaks links.
• Relinking one item often relinks the rest from the same folder — try that before fixing each by hand.
• Replace Footage preserves effects/keyframes; deleting + re-importing does not.
• AE auto-creates a "Solids" folder — don't scatter solids elsewhere or it regenerates duplicates.
• Scripts need app.beginUndoGroup/endUndoGroup or a batch becomes many separate undos.
• Applying effects by name needs the matchName, not the display name (e.g., "ADBE Gaussian Blur 2"), to be reliable across AE language versions.
• Allow Scripts to Write Files must be enabled in Preferences > Scripting & Expressions for scripts that save/render.
• Deep precomp nesting makes both performance and relinking worse — keep it shallow.

---

AE Project Organization — Detailed Reference

Full folder (bin) template

PROJECT.aep
├── 00_Output/        (final renders live next to project on disk)
01_Comps/             master & active comps
02_Precomps/          nested precomps (prefix PRE_)
03_Footage/           video clips
04_Images/            stills, logos, vector, textures
05_Audio/             music, VO, SFX
06_Solids/            AE auto-folder; leave it here
07_Assets_3D/         OBJ/C4D/3D model assets
08_Reference/         storyboards, briefs, temp ref
99_Old/               deprecated, kept until final

Numeric prefixes lock sort order. Keep the on-disk asset folders mirroring these bins so Collect Files stays clean.

Naming scheme

Item	Pattern	Example
Master comp	PROJ_section_v##	BRAND_main_v04
Sub/shot comp	PROJ_section_shot_v##	BRAND_intro_logo_v02
Precomp	PRE_descriptor	PRE_textReveal
Null/control	CTRL_role	CTRL_master
Solid/BG	BG_role	BG_gradient
Matte	MATTE_role	MATTE_logoTrack
Adjustment	ADJ_role	ADJ_grade

Rules: zero-pad versions; no spaces/special characters for farm/cross-OS safety; keep unique and short.

Label color system (example)

Color	Meaning
Red	Control / null layers
Blue	Footage
Green	Precomps
Yellow	Text
Purple	Adjustment / effects
Orange	Audio
Gray	Disabled / old

Set via right-click → Label. Customize names/colors in Preferences > Labels. Use Edit > Label > Select Label Group to select everything of one color.

Relink / missing footage — full workflow

1. Identify: missing items show as colored bars with "Missing" placeholders; the Project panel marks them.
2. Relink one to fix many: right-click a missing item → Replace Footage > File (or double-click it). Choose the relocated file. AE prompts to relink all other missing files found in the same folder — accept to fix the batch at once.
3. Enumerate: File > Dependencies > Find Missing Footage, Find Missing Fonts, Find Missing Effects to locate every broken dependency.
4. Swap assets: Replace Footage > File swaps the source while preserving all layer instances, effects, masks, and keyframes.

Collect Files (portable handoff)

• File > Dependencies > Collect Files.
• Options: Collect Source Files = All; enable Reduce Project to drop unused; optionally Generate Report.
• Produces a folder containing the .aep plus a (Footage) subfolder with every used asset, preserving relative links so the project opens anywhere.
• Always deliver/move projects as a Collect Files package, never a lone .aep.

Slimming a project

• File > Reduce Project — removes all items not used by the currently selected comp(s). Destructive to unused items; save first.
• File > Dependencies > Consolidate All Footage — merges duplicate imports of the same file.
• File > Dependencies > Remove Unused Footage — drops footage no comp references.
• Run these before Collect Files to keep the package small.

Scripting setup

• Enable Preferences > Scripting & Expressions > Allow Scripts to Write Files and Access Network for scripts that save or render.
• Run a script: File > Scripts > Run Script File....
• Dock a panel script: place the .jsx in (AE install)/Scripts/ScriptUI Panels/, restart AE, open from the Window menu.
• Wrap every batch in app.beginUndoGroup("...") / app.endUndoGroup() so it undoes in one step.
• Apply effects by matchName (internal id like "ADBE Gaussian Blur 2"), not the localized display name, for cross-version reliability. Use layer.property("ADBE Effect Parade").addProperty(matchName).

Pre-comp discipline details

• "Leave all attributes in the new composition" keeps the outer layer's transform; "Move all attributes" pushes them inside the precomp. Choosing wrong shifts/rescales the result.
• Trim precomp duration to the content; over-long precomps waste RAM/disk cache.
• Name and file precomps immediately; never leave "Pre-comp 1".
• Keep nesting shallow (2–3 levels) for performance and easier relinking/debugging.

---

Keep the project tidy and named well and footage relinks without a fight. Built by iart.ai — the AI motion agent for editable, on-brand motion graphics.