Skip to content

Parsers

Main Entry Point

parse 

parse(
    aep_file_path: str | PathLike[str],
    *,
    ae_preferences_dir: str | PathLike[str] | None = None,
) -> Application

Parse an After Effects (.aep) project file and return an Application instance.

This is the main entry point for the library. It parses the binary RIFX data and returns an Application object whose project attribute holds the full project tree.

Parameters:

  • aep_file_path (str | PathLike[str]) –

    Path to the .aep file.

  • ae_preferences_dir (str | PathLike[str] | None, default: None ) –

    Optional path to the AE preferences directory (e.g. C:/Users/<user>/AppData/Roaming/Adobe/After Effects/25.6). When provided, render settings and output module templates are parsed lazily when needed.

Example 
import py_aep

app = py_aep.parse("project.aep")
project = app.project
print(app.version)

new 

new(
    version: str = _DEFAULT_NEW_VERSION,
    *,
    ae_preferences_dir: str | PathLike[str] | None = None,
) -> Application

Creates a new project in After Effects, replicating the File > New > New Project menu command.

Returns an Application wrapping an empty Project (containing only the root folder and an empty render queue).

Parameters:

  • version (str, default: _DEFAULT_NEW_VERSION ) –

    The After Effects version to stamp into the file, formatted as "{major}.{minor}x{build}" (e.g. "26.0x67"). A file stamped at version N opens in After Effects N and later.

  • ae_preferences_dir (str | PathLike[str] | None, default: None ) –

    Optional path to the AE preferences directory (e.g. C:/Users/<user>/AppData/Roaming/Adobe/After Effects/26.0), required only for adding items to the render queue.

Example 
import py_aep

app = py_aep.new()
comp = app.project.root_folder.add_comp("Comp 1", 1920, 1080, 1.0, 10.0, 30.0)
app.project.save("new_project.aep")

Utilities

list_layers 

list_layers(file: str | PathLike[str]) -> list[str]

Return the selectable layer names of a layered file, top layer first.

The order and contents match After Effects' "Choose Layer" import dropdown: leaf layers only, top-most first. Duplicate names are possible (Photoshop does not enforce unique layer names).

Parameters:

  • file (str | PathLike[str]) –

    Path to a .psd, .psb, .ai, or .pdf file.

Raises:

  • ValueError –

    If the extension is not a layered format, or the file's layers cannot be enumerated (UnsupportedPsdLayersError / UnsupportedAiLayersError, both ValueError subclasses).

read_ai_layer_bounds 

read_ai_layer_bounds(
    file: str | PathLike[str], data: bytes | None = None
) -> list[Box | None]

Return each Illustrator/PDF layer's artwork bounds in document order.

The bounds are the box After Effects stores for a "Layer Size" import, in page points with the origin at the page's bottom-left corner, as (x0, y0, x1, y1). They are a conservative estimate of the artwork extent, not its true visual bounds - see the module docstring.

Parameters:

  • file (str | PathLike[str]) –

    Path to a .ai or .pdf file.

  • data (bytes | None, default: None ) –

    The file's bytes, if the caller already read them.

Returns:

  • list[Box | None] –

    One entry per layer in resolvers.ai_layers.read_ai_layers order

  • list[Box | None] –

    (bottom layer first), None for a layer with no artwork on the page.

Warns:

  • UserWarning –

    If the document has more than one artboard, where After Effects measures the second page and py_aep measures the first.

Raises:

  • UnsupportedAiLayersError –

    If the file is not a PDF-compatible document, has no layers, or uses PDF structures py_aep cannot read (compressed object streams, encryption, or a content-stream filter other than Flate).

footage_size 

footage_size(box: Box | None) -> tuple[int, int]

The footage pixel size After Effects derives from an artwork box.

The box reaches AE through the opti's signed 16.16 field, and AE sizes the footage from what it reads back, so the extent is quantized before it is ceilinged - an extent that lands a float hair above an integer must not gain a pixel. A layer with no artwork floors at 1x1.

Parameters:

  • box (Box | None) –

    An entry of read_ai_layer_bounds, or None for an empty layer.

probe_media 

probe_media(
    file: Path, data: bytes | None = None
) -> MediaInfo

Read footage metadata from a media file's header.

Parameters:

  • file (Path) –

    Path to the source media file (drives the format dispatch).

  • data (bytes | None, default: None ) –

    The file's bytes, if the caller already read them; probed in memory instead of re-reading file.

Raises: