jsx-script-creator

name: jsx-script-creator description: Create ExtendScript/JSX files that integrate with the Python-to-AE file-based command bridge

JSX Script Creator

This skill covers creating .jsx ExtendScript files for the After Effects automation bridge. Scripts live in ae_automation/mixins/js/ and are executed by Python's runScript() method.

How Scripts Are Executed

Python's runScript() in ae_automation/mixins/afterEffect.py does the following before sending a script to AE:

1. Reads the .jsx file from ae_automation/mixins/js/
2. Applies placeholder replacements from a _remplacements dict
3. Prepends minified json2.js + framework.js (all utility functions are available)
4. Wraps the script body in try { ... } catch(e) { _error = e.lineNumber + ' ' + e.toString(); } outputLogs(_error);
5. Writes the composed script to the cache folder
6. Copies it to the queue folder for AE to pick up

Critical implication: Your scripts must NOT include top-level try/catch or error handling. The wrapper handles that. Your script body is inserted directly into the try block.

Header Comment Convention

Use this format at the top of every new JSX file:

//
// <Descriptive Title>
// ------------------------------------------------------------
// Language: javascript
//

For simpler utility scripts, a shorter header is acceptable:

// <One-line description>
// Parameters: {param1}, {param2}, ...

Placeholder Syntax (Critical)

Placeholders use {name} notation. The distinction between quoted and bare is essential:

String parameters -- QUOTED: "{paramName}"

var comp = FindItemByName("{comp_name}");
var layer = FindLayerByComp("{comp_name}", "{layer_name}");
saveFile("{output_file}", JSON.stringify(data));

When Python does fileContent.replace("{comp_name}", "MyComp"), the result is "MyComp" -- a valid JS string literal.

Numeric parameters -- BARE: {paramName}

var c = app.project.items.addComp("{compName}", {compWidth}, {compHeight}, {pixelAspect}, {duration}, {frameRate});
layer.startTime = {startTime};
layer.stretch = {stretch};

When Python replaces {compWidth} with 1920, the result is the bare number 1920 -- a valid JS number literal.

Rule of thumb

• If the value should be a JavaScript string: wrap placeholder in double quotes "{param}"
• If the value should be a JavaScript number: use bare {param}
• If the value could be either (e.g., a property value): use "{param}" and parse at runtime with valueParser()

Python-side replacement dict

Keys in the _remplacements dict must include the braces:

self.runScript("my_script.jsx", {
    "{comp_name}": str(comp_name),
    "{layer_name}": str(layer_name),
    "{startTime}": str(start_time),  # str() even for numbers -- it's string replacement
    "{duration}": str(duration),
})

Available framework.js Utilities

These functions are automatically available in every script (prepended by runScript()):

Global variables

• CACHE_FODLER -- Path to cache directory (note: typo is intentional, do not fix)
• LOG_OUTPUT -- Boolean flag for log output
• _LOGS -- Internal log accumulator string

AE 1-Based Indexing

After Effects uses 1-based indexing everywhere:

// Project items: app.project.item(1) is the first item
for (var i = 1; i <= app.project.numItems; i++) {
    var item = app.project.item(i);
}

// Layers: comp.layer(1) is the topmost layer
for (var i = 1; i <= comp.numLayers; i++) {
    var layer = comp.layer(i);
}

New layers are always added at index 1 (topmost position in the layer stack).

Data Return Pattern

To send data back from AE to Python:

In JSX:

var result = {};
result.items = [];
for (var i = 1; i <= app.project.numItems; i++) {
    result.items.push({ name: app.project.item(i).name, index: i });
}
saveFile("output.json", JSON.stringify(result));

In Python:

import json
from ae_automation import settings

random_name = self.runScript("my_script.jsx", replacements)
time.sleep(2)  # wait for AE to finish

output_path = os.path.join(settings.CACHE_FOLDER, "output.json")
with open(output_path, "r") as f:
    data = json.load(f)

Structural Patterns

Pattern 1: Function + Call (preferred for complex logic)

//
// Update Layer Opacity
// ------------------------------------------------------------
// Language: javascript
//

function updateOpacity(compName, layerName, opacity) {
    var comp = FindItemByName(compName);
    if (!comp) {
        print("Comp not found: " + compName);
        return;
    }
    var layer = FindLayerByComp(compName, layerName);
    if (!layer) {
        print("Layer not found: " + layerName);
        return;
    }
    layer.opacity.setValue(opacity);
    print("Set opacity to " + opacity);
}

updateOpacity("{comp_name}", "{layer_name}", {opacity});

Pattern 2: Inline Script (for simple operations)

//
// Select Item By Name
// ------------------------------------------------------------
// Language: javascript
//

deselectAll();
var _id = FindItemIdByName("{itemName}");
if (_id !== null) {
    app.project.item(_id).selected = true;
    print("Selected: {itemName}");
}

ES3 Constraints

After Effects ExtendScript uses ECMAScript 3. The following modern JS features are NOT available:

Complete Example: New JSX Script

Here is a complete example of a script that collects composition info:

//
// Get Composition Details
// ------------------------------------------------------------
// Language: javascript
//

function getCompDetails(compName) {
    var comp = FindItemByName(compName);
    if (!comp) {
        print("Composition not found: " + compName);
        return;
    }

    var details = {
        name: comp.name,
        width: comp.width,
        height: comp.height,
        duration: comp.duration,
        frameRate: comp.frameRate,
        numLayers: comp.numLayers,
        layers: []
    };

    for (var i = 1; i <= comp.numLayers; i++) {
        var layer = comp.layer(i);
        details.layers.push({
            index: i,
            name: layer.name,
            inPoint: layer.inPoint,
            outPoint: layer.outPoint,
            enabled: layer.enabled
        });
    }

    saveFile("comp_details.json", JSON.stringify(details));
    print("Saved details for " + compName + " with " + comp.numLayers + " layers");
}

getCompDetails("{comp_name}");

And the Python side to call it:

def getCompDetails(self, comp_name):
    self.runScript("get_comp_details.jsx", {
        "{comp_name}": str(comp_name),
    })
    time.sleep(2)

    output_path = os.path.join(settings.CACHE_FOLDER, "comp_details.json")
    with open(output_path, "r") as f:
        return json.load(f)