effectcraft/docs/preferences.md

Settings, keyboard shortcuts, auto-save and crash recovery

Settings (Preferences)

EffectCraft ▸ Settings (macOS) or Edit ▸ Preferences (Windows/Linux), Cmd+Alt+;. The dialog has After Effects 2026's pages (General, Startup & Repair, Project, Composition, Previews, Appearance, Grids & Guides, Labels, Type, Import, Export, Audio, Disk, Memory & CPU, Video, 3D, Scripting & Expressions) with OK, Cancel, Previous and Next. Older page names still open the right page (prefs.open {"page": "Auto-Save"} opens Project, Media & Disk Cache opens Disk, Memory & Performance opens Memory & CPU).

The model is effectcraft_engine::prefs::Prefs: serde, versioned (version), addressed by dotted keys (general.undoLevels, autoSave.intervalMinutes, labels.3.name). It is stored as prefs.json through the session's ConfigStore (the desktop app uses the platform config directory: ~/Library/Application Support/EffectCraft on macOS, %APPDATA%\EffectCraft on Windows, $XDG_CONFIG_HOME/effectcraft on Linux; the web app can back the same trait with localStorage). Loading migrates older layouts, keeps unknown keys (from newer versions) and falls back to defaults for values that don't parse.

Commands (CLI, MCP, control channel):

Command	Parameters
prefs.get	{key?} (omit for everything)
prefs.set	{key, value} or {values: {key: value}}
prefs.reset	{page?} (omit for everything)
prefs.open	{page?} opens the Settings dialog
prefs.pages	the page schema: every row, its key, type, range and whether it is wired

Settings that change behaviour

• general.undoLevels: Levels of Undo
• general.pathPointSize: Path Point and Handle Size
• general.recentItems: Recent Projects Shown
• general.showToolTips: Show Tool Tips
• general.createLayersAtCompStart: Create Layers at Composition Start Time
• general.defaultSpatialLinear: Default Spatial Interpolation to Linear
• startup.showHomeOnLaunch: Show Home Screen When Launching
• startup.offerCrashRecovery: Offer to Open the Latest Auto-Save After a Crash
• project.useTemplate: New Project Loads Template
• project.templatePath: Template Project
• autoSave.enabled: Automatically Save Projects
• autoSave.intervalMinutes: Save Every
• autoSave.maxVersions: Maximum Project Versions
• autoSave.location: Auto-Save Location
• autoSave.folder: Custom Location
• autoSave.saveOnRenderStart: Save When Starting Render Queue
• composition.showRenderingProgress: Show Rendering Progress in Info Panel and Flowchart
• previews.adaptiveResolutionLimit: Adaptive Resolution Limit
• previews.cacheFramesWhenIdle: Cache Frames When Idle
• previews.fastPreviews: Fast Previews (Draft 3D, Faster Effects)
• appearance.theme: Theme
• appearance.brightness: Brightness
• appearance.useLabelColorForHandles: Use Label Color for Layer Handles and Paths
• grids.gridColor: Color
• grids.gridSpacing: Gridline Every
• grids.gridSubdivisions: Subdivisions
• grids.guideColor: Color
• grids.actionSafe: Action-safe
• grids.titleSafe: Title-safe
• import.stillFootage: Still Footage
• import.stillSeconds: Still Duration
• import.sequenceFps: Sequence Footage
• audio.outputDevice: Default Output (device list from the desktop host)
• audio.outputLeft: Left (Audio Output Mapping)
• audio.outputRight: Right (Audio Output Mapping)
• memory.layerCacheMb: Layer Cache
• memory.mediaCacheMb: Footage Frame Cache
• memory.previewCacheMb: Preview (RAM) Cache
• threeD.defaultRenderer: Default 3D Renderer
• labels.N.name / labels.N.color: the 16 label names and colours, used by the Label menu, the timeline, project panel, render queue and viewer handles
• general.switchesAffectNestedComps: a precomp layer's Quality (Draft / Wireframe) and Motion Blur switches limit the layers of the nested comp (viewer, Render Queue, render)
• general.preserveConstantVertexCount: adding or deleting mask / shape path vertices at one keyframe does the same on every other keyframe (added vertices split the matching segment)
• general.syncTimeRelatedItems: moving the current time moves it in the comps nested in this one and in the comps that nest it (through the precomp layers' timing)
• general.expressionPickWhipCompact: off, the pick whip writes match names (thisComp.layer("A")("transform")("opacity"))
• general.createSplitLayersAbove: where Edit ▸ Split Layer puts the new layer
• startup.showHomeOnOpenProject: the Home screen comes up after File ▸ Open / Open Recent
• composition.motionPath, composition.motionPathSeconds, composition.motionPathKeyframes: how much of a position motion path the viewer draws (all, none, N seconds or N keyframes around the current time)
• previews.showInternalWireframes: outlines of the layers inside a selected collapsed precomp
• previews.zoomQuality: Faster = nearest-neighbour viewer scaling, More Accurate = bilinear
• previews.displayProfile: the monitor's colour space for View ▸ Use Display Color Management
• appearance.useLabelColorForTabs: Composition / Timeline tabs show the comp's label colour, Effect Controls / Properties the layer's
• appearance.cycleMaskColors: new masks cycle through the mask colours (off: all the first)
• appearance.useGradients: soft gradient on panel tab strips
• grids.gridStyle, grids.guideStyle: lines, dashed lines or dots (grid, proportional grid, guides); grids.proportionalHorizontal / grids.proportionalVertical: View ▸ Show Proportional Grid divisions
• type.textEngine: South Asian and Middle Eastern shows the paragraph direction and the World-Ready composers in the Paragraph panel
• type.fontPreview: a "Sample" preview in each font of the Character panel's font menu
• type.recentFonts: how many recently used fonts head the font menu
• type.fontNamesInEnglish: off, fonts with a native-language family name show it
• import.reportMissingFrames: gaps in an image sequence's numbering are reported on import
• import.unlabeledAlpha: alpha of TGA / TIFF / movie footage (Ask opens Interpret Footage; Guess takes premultiplied for movies, straight for stills)
• import.dragImportAs: layered files dropped on the window import as footage or a comp
• export.defaultOutputFolder: where relative Render Queue outputs go
• export.segmentSequences, export.segmentSequenceFiles: sequences split into numbered folders of N files; export.segmentMovies, export.segmentMovieMb: movies split into numbered files of about N MB (cut at the frame count the output's data rate gives)
• export.appendBitsToName: Comp 1.png → Comp 1_16bpc.png
• audio.previewSampleRate: the rate previews are mixed at (and the device is opened at, when it supports it)
• disk.diskCacheEnabled, disk.diskCacheMaxGb, disk.diskCacheFolder: the persistent disk cache of processed layers
• disk.mediaCacheFolder: audio waveform summaries kept between sessions (Peaks/)
• disk.conformedMediaFolder: decoded (conformed) footage audio, written once per file and sample rate and read back instead of decoding again
• memory.ramReservedGb: the cache budgets together leave this much physical memory free
• memory.reduceCacheWhenLow: cache budgets halve while the system is low on memory (checked every 10 s by the desktop app)
• video.enableOutput, video.device, video.outputDuringPlayback, video.mirrorOnMonitor, video.disableWhenBackground: Video Preview, a second window (or full screen on the display it is on) showing the composition frame, Mercury Transmit-style
• threeD.showReferenceAxes: world X/Y/Z axes in the viewer corner of comps with 3D layers
• threeD.extendedViewer: 3D layers reaching beyond the comp frame are outlined on the pasteboard
• threeD.realtimeShadows: draft (Fast Previews) renders keep 3D shadows
• scripting.allowScriptsWriteFiles: the scripting file / network gate (and File.execute())
• scripting.warnExecutingFiles: File.execute() asks before opening a file
• scripting.editorFontSize, scripting.syntaxHighlighting, scripting.lineNumbers, scripting.autoComplete (Tab accepts), scripting.bracketMatching, scripting.wordWrap: the Timeline's expression editor
• scripting.errorBanner: a banner along the bottom of the Composition panel names the first failing expression (click: reveal it)

Display-only settings

These rows are in the dialog for After Effects parity and are stored, but have no EffectCraft behaviour to change. prefs.pages reports them with "live": false; a test keeps this list in step with the schema.

• general.useSystemColorPicker: EffectCraft has one colour picker on every platform and the web; there is no pure-Rust way to open the system colour panels.
• composition.hardwareAcceleratePanels: the Composition, Layer and Footage panels are always drawn by the GPU (egui on wgpu).
• scripting.enableJsDebugger: the JavaScript engine has no step debugger; script errors report their file and line in the Script Console.

Keyboard shortcuts

Edit ▸ Keyboard Shortcuts (Cmd+Alt+') opens the shortcut editor: an on-screen keyboard showing which keys are assigned for the held modifiers (purple: application-wide, green: panel-specific, both: split), modifier toggles, a searchable list of every command (all engine commands, menu entries with bound parameters and the frontend's tool / panel commands), and a preset menu.

• Presets. "EffectCraft Default" is After Effects' default layout and is read-only; editing it creates a "Custom" copy. Custom presets store only their differences from the default and can be duplicated, renamed, deleted, exported and imported (JSON). The active preset is what the menus show and what the shortcut dispatcher runs.
• Assigning. Select a command, then press keys in the shortcut field (or type them), or click a key on the keyboard with the modifiers toggled. Conflicts with other commands in an overlapping scope are listed before you assign.
• Scope. Menu and engine commands are application-wide; timeline commands work in the Timeline and viewer commands in the Composition panel.

Commands: shortcuts.list {query?, keys?, assigned?}, shortcuts.set {command, params?, keys}, shortcuts.reset {command?}, shortcuts.preset {op: select|new|duplicate|delete|rename, name?, from?, newName?}, shortcuts.export {preset?, path?}, shortcuts.import {path? | preset?}, shortcuts.conflicts.

Auto-save and crash recovery

• Every n minutes (Settings ▸ Project ▸ Auto-Save) a project with unsaved changes is written to an EffectCraft Auto-Save folder next to it (or the custom folder) as <name> auto-save N.ecproj. Slots rotate through 1…maximum versions, overwriting the oldest. Untitled projects go to the custom folder, or to Auto-Save in the config directory.
• Every project and auto-save write is atomic: a temporary file is written and flushed, then renamed over the target, so a crash mid-write leaves the previous file intact.
• While the app runs, session.lock in the config directory records the open project and its latest auto-save. A clean quit removes it. If it is still there at the next launch, the app offers to open the latest auto-save (Settings ▸ Startup & Repair can turn this off).
• File ▸ Open Recent lists recent projects (stored in the settings), File ▸ Revert reloads the saved project, File ▸ Increment and Save saves Intro.ecproj as Intro 2.ecproj.

Commands: file.autoSave (now), file.recoveryInfo, file.openRecent {index? | path?}, file.clearRecent, file.revert, file.incrementAndSave.