ae-config-builder

name: ae-config-builder description: Create and validate JSON automation configs for the After Effects automation pipeline

AE Config Builder

This skill covers creating and validating JSON configuration files that drive the After Effects automation pipeline. Configs are loaded by botMixin.startBot() and control the entire workflow from project setup through rendering.

Top-Level Structure

{
  "project": { ... },
  "timeline": [ ... ],
  "templates": { ... }
}

• project (required) -- Output settings, composition parameters, and resource definitions
• timeline (required) -- Array of scene objects, each with custom actions
• templates (optional) -- Reusable action templates with variable substitution

Project Section

All fields and their types:

comp_end_time Dual Format

"comp_end_time": 15
"comp_end_time": "00:00:15"

Both are valid. The number format specifies seconds directly. The string format is parsed by timeToFrames().

Debug Mode

Setting "debug": true prevents AE from launching and skips all UI interaction. Useful for:

• Validating config structure
• Testing config loading
• CI/CD pipelines
• Dry-run validation

Path Resolution

Paths in project_file and output_dir can be relative. They are resolved relative to the config file's directory by startBot():

{
  "project": {
    "project_file": ".\\my_template.aep",
    "output_dir": ".\\output"
  }
}

Use .\ or ./ prefix for relative paths. Forward slashes work on all platforms.

Resources Array

Resources are external assets (images, audio, video) imported into the AE project:

"resources": [
  {
    "type": "image",
    "name": "background",
    "path": "C:/assets/bg.png"
  },
  {
    "type": "audio",
    "name": "bgm",
    "path": "C:/assets/music.mp3",
    "duration": 30
  },
  {
    "type": "video",
    "name": "footage",
    "path": "C:/assets/clip.mp4"
  }
]

• type -- "image", "audio", or "video"
• name -- Identifier used to reference this resource in timeline actions
• path -- Absolute path to the asset file
• duration -- Optional; for MP3 audio the duration is auto-detected if omitted

Timeline Section

An array of scene objects processed in order:

"timeline": [
  {
    "name": "intro_scene",
    "duration": 5,
    "startTime": 0,
    "template_comp": "IntroTemplate",
    "reverse": false,
    "custom_actions": [ ... ]
  },
  {
    "name": "content_scene",
    "duration": 10,
    "startTime": 5,
    "template_comp": "ContentTemplate",
    "reverse": false,
    "custom_actions": [ ... ]
  }
]

Scene Object Fields

Custom Actions

Each action object must have a change_type field that routes to the corresponding handler. See references/config-schema.md for the complete catalogue of all 8 change types with full field definitions.

Quick Reference

Property Dot-Notation

Layer properties use dot-separated paths that propertyParser() traverses:

"Text.Source Text"          -- Text layer content
"Text.Path Options.Path"    -- Text path
"Transform.Position"        -- Layer position [x,y]
"Transform.Scale"           -- Layer scale [x,y]
"Transform.Opacity"         -- Layer opacity (0-100)
"Transform.Rotation"        -- Layer rotation in degrees
"Effects.Color_01.Color"    -- Effect parameter (effect name.property)
"Effects.Slider_01.Slider"  -- Effect slider value

The first segment selects the property group, subsequent segments drill into sub-properties.

Value Formats

Strings

"value": "Hello World"

Hex Colors

"value": "#FF0000",
"property_type": "color"

When property_type is "color", the hex value is auto-converted to AE's normalized RGBA format ("1.0,0.0,0.0,1") by hexToRGBA() before being sent to JSX.

Arrays (as strings)

"value": "[960,540]"

Arrays are passed as string representations. The valueParser() function in framework.js detects the [ prefix and parses them into actual arrays.

Numbers

"value": "100"

Numeric values are also passed as strings and parsed by valueParser().

Templates Section

Define reusable action groups with {key} variable substitution:

{
  "templates": {
    "update_title": {
      "custom_actions": [
        {
          "change_type": "update_layer_property",
          "comp_name": "{comp}",
          "layer_name": "Title",
          "property_name": "Text.Source Text",
          "property_type": "string",
          "value": "{title_text}"
        },
        {
          "change_type": "update_layer_property",
          "comp_name": "{comp}",
          "layer_name": "Title",
          "property_name": "Effects.Color_01.Color",
          "property_type": "color",
          "value": "{title_color}"
        }
      ]
    }
  },
  "timeline": [
    {
      "name": "scene_1",
      "template_comp": "SceneTemplate",
      "duration": 5,
      "startTime": 0,
      "custom_actions": [
        {
          "change_type": "template",
          "template_name": "update_title",
          "template_values": {
            "comp": "scene_1_SceneTemplate",
            "title_text": "Welcome",
            "title_color": "#FFFFFF"
          }
        }
      ]
    }
  ]
}

The template change_type looks up data["templates"][template_name], replaces all {key} placeholders with template_values, then recursively processes each resulting action through parseCustomActions().