Skip to content

Import options

ImportOptions

Options for importing a file into an After Effects project.

This is a parameter container used by Project.import_file(). It validates the import settings before the actual import operation.

Unlike most py_aep classes, ImportOptions has no chunk backing - import settings are not stored in the .aep binary format.

Example 
from pathlib import Path
from py_aep import ImportOptions, ImportAsType

opts = ImportOptions(Path("footage/shot_001.png"))
opts.sequence = True
opts.import_as = ImportAsType.FOOTAGE

See: https://ae-scripting.docsforadobe.dev/other/importoptions/

Attributes

file 

file: Path

The file to be imported. If a file is set in the constructor, you can access it through this attribute. Read / Write.

force_alphabetical 

force_alphabetical: bool

When True and sequence is also True, use alphabetical order for sequence frame numbering. Read / Write.

Setting True resets range_start and range_end to 0 (matching After Effects: an alphabetical sequence cannot carry a frame range).

import_as 

import_as: ImportAsType

How to import the file. Read / Write.

layer_dimensions 

layer_dimensions: str | None

Footage dimensions for a layer_index import: "document" (the full canvas) or "layer" (the layer's content box), matching the "Footage Dimensions" option of AE's import dialog. None (the default) follows the machine's sticky "Footage Dimensions" preference for a .psd/.psb import when the project was parsed with an ae_preferences_dir, and imports at document size otherwise (always, for .ai/.pdf). Read / Write.

py_aep extension: ExtendScript exposes no layer-selection API.

Note

"layer" is only supported for .psd/.psb. AE's own dialog defaults to Layer Size for .ai/.pdf, but computing an AI layer's artwork bounds requires rendering the PDF content, so py_aep raises NotImplementedError there.

layer_index 

layer_index: int | None

The single layer to import from a layered file (.psd/.psb/ .ai/.pdf), as its 0-based position in the list returned by list_layers (top layer first - the order of the "Choose Layer" dropdown of AE's import dialog). None (the default) imports the file like AE's "Merged Layers" / whole-document option. Only valid with ImportAsType.FOOTAGE. Read / Write.

py_aep extension: ExtendScript exposes no layer-selection API. An index (not a name) selects the layer because layered files may contain several layers with the same name; AE's own dialog disambiguates duplicates by dropdown position.

Raises:

  • ValueError –

    On import, if the index is out of range for the file's selectable layers (see list_layers).

layer_styles 

layer_styles: str | None

How a Photoshop (.psd/.psb) import treats the source layer styles, matching the "Layer Options" of AE's import dialog: "editable" (Editable Layer Styles), "merge" (Merge Layer Styles into Footage) or "ignore" (Ignore Layer Styles). None (the default) follows the machine's sticky "Layer Options" preference when the project was parsed with an ae_preferences_dir, falling back to AE's dialog default for the context: "editable" for a COMP / COMP_CROPPED_LAYERS import, "merge" for a FOOTAGE import of a single layer. Read / Write.

py_aep extension: ExtendScript exposes no layer-styles API. AE's own importFile silently follows the sticky preference; py_aep mirrors that when a preferences directory is available. Pass an explicit value for behavior that does not depend on the machine.

Valid combinations (checked at import time): a FOOTAGE import accepts "merge"/"ignore" and requires layer_index (AE's "Merged Layers" whole-document import - layer_index=None - always flattens the styles into the composite and offers no choice); a COMP import accepts "editable"/"merge". Note the naming collision in AE's dialog: "Merged Layers" (flatten the whole document, expressed as layer_index=None) is unrelated to "merge" (bake the styles into one layer's raster).

Raises:

  • ValueError –

    On import, if the value is not offered for the import context (see above), or if the file is not .psd/.psb.

range_end 

range_end: int

The last frame number of the clipping range for a numbered image sequence import, inclusive. 0 (with range_start 0) imports every frame. Read / Write.

A range_end beyond the last existing frame keeps the range: After Effects treats the missing tail frames as implied (rendered as placeholder bars), and py_aep writes the same start_frame/end_frame bounds. The resulting footage duration is not clamped to After Effects' 3-hour ceiling - AE 2026 opens a longer ranged sequence without complaint.

Raises:

  • ValueError –

    If set while force_alphabetical is True, or if the value does not fit the sspc end_frame field (a u4: 0..4294967295).

range_start 

range_start: int

The first frame number of the clipping range for a numbered image sequence import, inclusive. 0 (with range_end 0) imports every frame. Read / Write.

Frame numbers refer to the digits in the filenames, not ordinal positions. Has no effect unless sequence is True. A range_end of 0 with a non-zero range_start is rejected at import time, as is range_end < range_start (both matching After Effects).

Raises:

  • ValueError –

    If set while force_alphabetical is True (After Effects: "You cannot set sequence range start for an alphabetical sequence"), or if the value does not fit the sspc start_frame field (a u4: 0..4294967295).

sequence 

sequence: bool

When True, import the file as part of a numbered image sequence. Read / Write.

Functions

can_import_as 

can_import_as(type: int | ImportAsType) -> bool

Check whether the file can be imported as the given type.

Gates on what py_aep can actually import: the per-extension capability table (get_import_as_types) reflects After Effects, while a file whose format py_aep does not implement (absent from data.file_formats, or marked unsupported) returns False for every type. ImportAsType.PROJECT is never importable (py_aep does not implement project import for any format), so it always returns False even though AE can import .mov/.m4a/.aep/.aet as a project.

Parameters:

Returns:

  • bool –

    True if the file can be imported as type.

is_file_name_numbered 

is_file_name_numbered() -> tuple[bool, int]

Check whether the filename ends with a number.

Returns:

  • bool –

    A tuple of (is_numbered, first_number) where

  • int –

    is_numbered is True when the filename stem ends with

  • tuple[bool, int] –

    digits and first_number is the parsed integer value (or

  • tuple[bool, int] –

    0 when not numbered).