Parsers¶

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.

• platform (str | None, default: None ) –

  The After Effects platform the project is for: "windows" or "macos". Footage and render output paths py_aep writes are stored in that platform's style (C:\x <-> /x, see platform_path), and imported footage is recorded the way After Effects on that platform records it: BMP and GIF files take the platform's importer code (After Effects on the other platform refuses an image sequence tagged for it), and on Windows a HEIC file has no alpha channel. Defaults to the running operating system.

import py_aep

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

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. The major must be an After Effects release: 15 (CC 2018) to 18, or 22 and later. A release newer than 26 gets the After Effects 2026 project and file-format stamp, so the file also opens in After Effects 2026.

• 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.

• platform (str | None, default: None ) –

  The After Effects platform the project is for, as in parse. It also selects the header stamps and the GPU renderer (Metal on macOS, CUDA on Windows) a project created on that platform carries. Defaults to the running operating system.

Raises:

• ValueError –

  If version is malformed, names a major before 26 that py_aep has no file-format stamp for (before 15, or 19 to 21), or has a major or build above 255 or a minor above 15 (the head chunk's field widths).

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")

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).

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).

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.

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:

• NotImplementedError –

  If header probing is not implemented for the file's extension.

• ValueError –

  If the file is not a valid file of its format, or is truncated or malformed.

path in the style of After Effects on the target platform.

After Effects on Windows opens a macOS path /Users/x/a.png as C:\Users\x\a.png (and /Volumes/v/a.png as C:\Volumes\v\a.png), measured on AE 2026; the reverse is the inverse of that. A Windows path on another drive or on a UNC share has no such counterpart, so it maps to a macOS mount point - D:\x to /Volumes/D/x, \\server\share\x to /Volumes/share/x (the usual macOS mount of a share, not measured). A path already in the target style, or a relative one, is returned unchanged.

Parameters:

• path (str) –

  An absolute path in either style.

• windows (bool) –

  True for After Effects on Windows, False for macOS.