Helper functions

Every script that runs in a job can use the nexrender object. Its helpers cover the things most scripts start with: finding compositions and layers by name, replacing footage, and logging. The helpers only exist while Nexrender runs your script. To run the same file in After Effects by hand, see Run the same script in After Effects.

Properties

Property	Value
`nexrender.renderCompositionName`	The name of the composition the job renders, from `template.composition`.
`nexrender.defaultCompositionName`	`"*"`, the name the layer helpers use when you pass `null` as the composition. It matches every composition.
`nexrender.types`	The After Effects classes the helpers work with: `CompItem`, `FolderItem`, `FootageItem`, `AVLayer`, `ShapeLayer`, `TextLayer`, `CameraLayer`, `LightLayer`, `Property`, and `PropertyGroup`.

Composition names and paths

Every helper that takes a composition name accepts:

An exact composition name, such as "intro". Names are case-sensitive.
"*" for every composition in the project. The selectLayersBy... helpers also take null for this.
A path of nested compositions joined with ->, such as "main->intro". It picks the intro composition only if main uses it. Paths can go deeper: "main->intro->lower_third".

A path picks which composition to work on, not one use of it. If intro is also used in another composition, your changes show up there too.

Without a composition name, a helper searches every composition. If the same layer name appears in several compositions, the callback runs for each of them.

nexrender.log

nexrender.log(message)

Writes a line to the job’s render log, prefixed with NX:. Read the log with GET /jobs/{id}/logs or nexrender job logs JOB_ID.

nexrender.log("Rendering " + nexrender.renderCompositionName);
nexrender.log(JSON.stringify({ layers: 12, missing: [] }));

Render log

NX: Rendering main
NX: {"layers":12,"missing":[]}

message is converted to a string. Use JSON.stringify to log arrays and objects.

The render log hides some values: IDs like the job’s show as [render id], paths on the render node as [local path], the query string of a URL as ?[parameters], and email addresses as [email]. Characters outside ASCII, such as €, may show as ?, even though your script handles them correctly.

nexrender.selectCompositionsByName

nexrender.selectCompositionsByName(name, callback)

Calls callback(comp) for every composition that matches name.

string

required

A composition name, "*", or a -> path. See Composition names and paths. It can’t be null.

function

required

Called with each matching CompItem.

Throws nexrender: Couldn't find any compositions by provided name (NAME) when nothing matches.

nexrender.selectCompositionsByName("*", function (comp) {
    comp.duration = 10;
});

nexrender.selectLayersByName

nexrender.selectLayersByName(compositionName, layerName, callback, types, continueOnMissing)

Calls callback(layer, layerName) for every layer named layerName in the matching compositions.

string | null

required

A composition name, "*", or a -> path. null searches every composition.

string

required

The exact layer name. It’s case-sensitive.

function

required

Called with each matching layer and the name you searched for.

array

Accepted for compatibility, but layers of every type match. To act on one kind of layer only, check it in your callback: if (layer instanceof TextLayer). Pass null here when you need continueOnMissing.

boolean

default:"false"

Set to true to skip the error when no layer matches. A composition that doesn’t exist still throws.

Throws nexrender: Couldn't find any layers by provided name (NAME) inside a composition: COMPOSITION when no layer matches, unless continueOnMissing is true.

nexrender.selectLayersByName("main->single_product", "var_product_name_1", function (layer) {
    if (layer instanceof TextLayer) {
        layer.property("Source Text").setValue("CyberPulse Keyboard");
    }
});

nexrender.selectLayersByType

nexrender.selectLayersByType(compositionName, type, callback, types, continueOnMissing)

Calls callback(layer) for every layer of class type in the matching compositions.

string | null

required

A composition name, "*", or a -> path. null searches every composition.

class

required

A layer class: TextLayer, ShapeLayer, AVLayer, CameraLayer, or LightLayer.

function

required

Called with each matching layer.

array

Accepted for compatibility, but not applied. Pass null here when you need continueOnMissing.

boolean

default:"false"

Set to true to skip the error when no layer matches. A composition that doesn’t exist still throws.

Throws nexrender: Couldn't find any layers by provided type (TYPE) inside a composition: COMPOSITION when no layer matches, unless continueOnMissing is true.

var names = [];
nexrender.selectLayersByType("intro", TextLayer, function (layer) {
    names.push(layer.name);
});
nexrender.log("Text layers in intro: " + names.join(", "));

nexrender.selectLayersByIndex

nexrender.selectLayersByIndex(compositionName, index, callback, types, continueOnMissing)

Calls callback(layer, index) with the layer at index in each matching composition.

string | null

required

A composition name, "*", or a -> path. null searches every composition.

number

required

The layer’s index. It starts at 1, as in After Effects.

function

required

Called with the layer and its index.

array

Not used by this helper. Check layer instanceof TextLayer in your callback instead.

boolean

default:"false"

Set to true to skip Nexrender’s error when no layer is found. Check the layer count with comp.numLayers first: After Effects itself can raise an error for an index past the last layer.

nexrender.selectLayersByIndex("main", 1, function (layer, index) {
    nexrender.log("Layer " + index + " is " + layer.name);
});

nexrender.replaceFootage

nexrender.replaceFootage(layer, filePath, sequence, removeOldFootage)

Imports a file into the project and makes it the layer’s source. Returns true, or false when layer is empty.

AVLayer

required

A layer with a footage source, such as an image or video layer.

string

required

The absolute path of the file to import. Files you download with a static asset are in the job folder: NX.get("nxWorkpath") + "/photo.png".

boolean

default:"false"

Set to true to import the file as the first frame of an image sequence.

boolean

default:"false"

Set to true to delete the previous footage item from the project. After Effects also deletes every other layer that uses it.

Throws nexrender: Trying to create a file replacement for an unknown file: PATH when the file doesn’t exist.

nexrender.selectLayersByName("main->single_product", "var_product_photo_1", function (layer) {
    nexrender.replaceFootage(layer, NX.get("nxWorkpath") + "/photo.png");
});

nexrender.changeValueForKeypath

nexrender.changeValueForKeypath(layer, keys, change)

Sets a value or an expression on a property found by a path of property names. This is how data assets change layers.

Layer

required

The layer to change.

array

required

Property names from the layer down to the property, such as ["Transform", "Opacity"] or ["Effects", "Glow", "Glow Radius"].

object

required

{ "value": VALUE } to set the property’s value, or { "expression": "EXPRESSION" } to set its expression.

Throws nexrender: Can't find a property sequence ... when a name in keys doesn’t exist on the layer.

nexrender.selectLayersByName("main->single_product", "var_cta_text", function (layer) {
    nexrender.changeValueForKeypath(layer, ["Transform", "Opacity"], { value: 50 });
    nexrender.changeValueForKeypath(layer, ["Transform", "Rotation"], { expression: "time * 30" });
});

Other members

nexrender.typesMatch(types, layer) and nexrender.evaluate(layer, expression) are used inside Nexrender, by the helpers and by data assets. Your scripts don’t need them.

Errors

Every helper error starts with nexrender:. An error you don’t catch stops the script and fails the job with that message, before the render starts. To carry on when a layer is missing, pass continueOnMissing. For a missing composition, or anything else, wrap the call in try/catch:

try {
    nexrender.selectLayersByName("main", "Optional badge", function (layer) {
        layer.enabled = NX.get("showBadge") === true;
    });
} catch (error) {
    nexrender.log("No badge layer, skipping: " + error.message);
}

Essentials

Managing Templates

Rendering Jobs

Scripting

Fonts Management

Properties

Composition names and paths

nexrender.log

nexrender.selectCompositionsByName

nexrender.selectLayersByName

nexrender.selectLayersByType

nexrender.selectLayersByIndex

nexrender.replaceFootage

nexrender.changeValueForKeypath

Other members

Errors

​Properties

​Composition names and paths

​nexrender.log

​nexrender.selectCompositionsByName

​nexrender.selectLayersByName

​nexrender.selectLayersByType

​nexrender.selectLayersByIndex

​nexrender.replaceFootage

​nexrender.changeValueForKeypath

​Other members

​Errors

Properties

Composition names and paths

nexrender.log

nexrender.selectCompositionsByName

nexrender.selectLayersByName

nexrender.selectLayersByType

nexrender.selectLayersByIndex

nexrender.replaceFootage

nexrender.changeValueForKeypath

Other members

Errors