Project

Project ¶

The Project object represents an After Effects project. Attributes provide access to specific objects within the project, such as imported files or footage and compositions, and also to project settings such as the timecode base.

Example

from py_aep import parse

app = parse("project.aep")
project = app.project
print(project.file)
for item in project:
    ...

See: https://ae-scripting.docsforadobe.dev/general/project/

Attributes¶

active_item ¶

active_item: Item | None

The item that is currently active and is to be acted upon, or None if no item is currently selected or if multiple items are selected. Read-only.

audio_sample_rate ¶

audio_sample_rate = ChunkField[float](
    "_adfr",
    "value",
    validate=validate_one_of(
        (22050, 32000, 44100, 48000, 96000)
    ),
)

The project audio sample rate in Hz.

Allowed values: 22050, 32000, 44100, 48000, 96000.

Note

Not exposed in ExtendScript

bits_per_channel ¶

bits_per_channel = enum(
    BitsPerChannel,
    "_nnhd",
    "bits_per_channel",
    post_set=lambda obj: _sync_nhed_field(
        "bits_per_channel"
    ),
)

The color depth of the current project, either 8, 16, or 32 bits. Read / Write.

color_management_system ¶

color_management_system: ColorManagementSystem

The color management system used by the project (Adobe or OCIO). Available in CC 2024 and later. Read / Write.

compensate_for_scene_referred_profiles ¶

compensate_for_scene_referred_profiles = bool(
    "_acer",
    "value",
    transform=bool,
    reverse=int,
    min_version=16,
)

When True, After Effects compensates for scene-referred profiles when rendering.

compositions ¶

compositions: list[CompItem]

All the compositions in the project.

display_color_space ¶

display_color_space: str

The name of the display color space used for the project (e.g., "ACES/sRGB"). Only relevant when color_management_system is OCIO. "None" when not set. Read / Write.

Assign a (display, view) tuple or a "display/view" string. Writable only in OCIO mode (the chunk stores an OCIO display + view by name). In Adobe CMS mode the display uses the operating system's monitor profile, which is not stored in the project (the pdvc chunk is an empty {}, unlike PwCs/working_space which embeds the full ICC), so assigning raises NotImplementedError.

Note

Not exposed in ExtendScript

display_start_frame ¶

display_start_frame = ChunkField[int](
    "_nnhd",
    "display_start_frame",
    validate=validate_one_of((0, 1)),
    post_set=lambda obj: _sync_nhed_field(
        "frames_count_type"
    ),
)

The start frame number for the project display (0 or 1). An alternate way of setting the Frame Count menu setting. Read / Write.

effect_names ¶

effect_names: list[str]

The names of all effects used in the project. Read-only.

expression_engine ¶

expression_engine: str

The Expressions Engine setting in the Project Settings dialog box ("extendscript" or "javascript-1.0"). Read / Write.

feet_frames_film_type ¶

feet_frames_film_type = enum(
    FeetFramesFilmType,
    "_nnhd",
    "feet_frames_film_type",
    post_set=lambda obj: _sync_nhed_field("_display_byte"),
)

The film type for feet+frames timecode display, either MM16 (16mm) or MM35 (35mm). Read / Write.

file ¶

file: str

The full path to the project file. Read-only.

folders ¶

folders: list[FolderItem]

All the folders in the project.

footage_timecode_display_start_type ¶

footage_timecode_display_start_type = enum(
    FootageTimecodeDisplayStartType,
    "_nnhd",
    "footage_timecode_display_start_type",
    post_set=lambda obj: _sync_nhed_field(
        "footage_timecode_display_start_type"
    ),
)

The Footage Start Time setting in the Project Settings dialog box, which is enabled when Timecode is selected as the time display style. Read / Write.

footages ¶

footages: list[FootageItem]

All the footages in the project.

frames_count_type ¶

frames_count_type = enum(
    FramesCountType,
    "_nnhd",
    "frames_count_type",
    post_set=lambda obj: _sync_nhed_field(
        "frames_count_type"
    ),
)

The Frame Count menu setting in the Project Settings dialog box. Read / Write.

frames_use_feet_frames ¶

frames_use_feet_frames = bool(
    "_nnhd",
    "frames_use_feet_frames",
    post_set=lambda obj: _sync_nhed_field("_feet_byte"),
)

When True, the Frames field in the UI is displayed as feet+frames. Read / Write.

gpu_accel_type ¶

gpu_accel_type = enum(
    GpuAccelType, "_gpug_utf8", "value", min_version=13
)

The GPU acceleration type for the project. None if not recognised. Read / Write.

icc_profile_dirs ¶

icc_profile_dirs: list[Path] | None

Directories scanned to resolve ICC profiles when writing an Adobe-CMS working space. None (default) auto-discovers the standard Adobe Color directories. Assign a list of folders containing .icc/ .icm files to override (e.g. for a non-default install or CI).

items ¶

items: dict[int, Item]

All the items in the project. Read-only.

linear_blending ¶

linear_blending: bool

When True, linear blending is used for the project. When False, the standard blending mode is used. Read / Write.

linearize_working_space ¶

linearize_working_space: bool

When True, the working color space is linearized for blending operations. Read / Write.

lut_interpolation_method ¶

lut_interpolation_method: LutInterpolationMethod

The LUT interpolation method for the project (Trilinear or Tetrahedral). Read / Write.

num_items ¶

num_items: int

Return the number of items in the project.

Note

Equivalent to len(project.items)

ocio_configuration_file ¶

ocio_configuration_file: str

The OCIO configuration file for the project. Only relevant when color_management_system is OCIO. Read / Write.

project_name ¶

project_name: str

The name of the project, derived from the file name.

render_queue ¶

render_queue: RenderQueue | None

The Render Queue of the project. Read-only.

revision ¶

revision = ChunkField[int](
    "_head", "file_revision", validate=validate_u2
)

The current revision of the project. Every user action increases the revision number by one. A new project starts at revision 1. Read / Write.

Note

This attribute is read-only in ExtendScript.

root_folder ¶

root_folder: FolderItem

The root folder. This is a virtual folder that contains all items in the Project panel, but not items contained inside other folders in the Project panel. Read-only.

time_display_type ¶

time_display_type = enum(
    TimeDisplayType,
    "_nnhd",
    "time_display_type",
    post_set=lambda obj: _sync_nhed_field("_display_byte"),
)

The time display style, corresponding to the Time Display Style section in the Project Settings dialog box. Read / Write.

transparency_grid_thumbnails ¶

transparency_grid_thumbnails = bool(
    "_nnhd",
    "transparency_grid_thumbnails",
    post_set=lambda obj: _sync_nhed_field(
        "transparency_grid_thumbnails"
    ),
)

When True, thumbnail views use the transparency checkerboard pattern. Read / Write.

used_fonts ¶

used_fonts: list[dict[str, Any]]

Returns an Array of Objects containing references to used fonts and the Text Layers and times on which they appear in the current Project. Read-only.

Each entry is {"font": FontObject, "used_at": [...]}, where every used_at record is {"layer_id": int, "layer_time": float} - one per source-text keyframe whose document references that font (a single record at time 0 for an unanimated document). A document with several fonts contributes one record per distinct font. Entries are sorted by PostScript name, matching After Effects.

Note

layer_time is in LAYER time, not composition time - After Effects names it layerTimeD because Source Text's value_at_time expects layer time, unlike other properties.

working_gamma ¶

working_gamma = ChunkField[float](
    "_dwga",
    "working_gamma",
    validate=validate_one_of((2.2, 2.4)),
)

The gamma value used for the working color space, either 2.2 or 2.4. Read / Write.

working_space ¶

working_space: str

The name of the working color space (e.g., "sRGB IEC61966-2.1", "ACEScg", "None"). Read / Write.

In OCIO mode, assigning any color space, role, alias, or display/view pair of ocio_configuration_file rewrites the embedded profile JSON (AE identifies it by name, no ICC data). The config must be resolvable, because the envelope AE writes depends on which of those kinds the name is; ValueError is raised if it cannot be located or the name is not in it.

In Adobe CMS mode, the matching ICC profile is discovered on disk (see icc_profile_dirs) and embedded; ColorProfileNotFoundError is raised if it is not installed.

xmp_packet ¶

xmp_packet = ChunkField["ET.Element | None"](
    "_aep",
    "_xmp",
    transform=lambda s: (
        fromstring(s) if s and strip() else None
    ),
    reverse=lambda el: (
        tostring(el, encoding="unicode")
        if el is not None
        else ""
    ),
)

The XMP packet for the project, containing metadata. None when the project has no XMP packet (e.g. projects created via py_aep.new()). Read / Write.

Functions¶

auto_fix_expressions ¶

auto_fix_expressions(old_text: str, new_text: str) -> None

Automatically replaces text found in broken expressions in the project, if the new text causes the expression to evaluate without errors.

py_aep cannot evaluate expressions, and After Effects' actual gate (is the expression currently erroring) is runtime state that is not stored in the project file. Instead, py_aep replaces the quoted forms "old_text" and 'old_text' in EVERY enabled expression of the project. Divergence from After Effects (probed AE 2026): an expression that evaluates cleanly but contains the quoted text is rewritten here, while After Effects leaves it untouched. Matching After Effects: disabled expressions are never modified, both quote styles are fixed, and quoted occurrences inside comments of a rewritten expression are replaced too.

Parameters:

old_text (str) –

The text to replace.
new_text (str) –

The new text.

consolidate_footage ¶

consolidate_footage() -> int

Merge duplicate footage items that share the same source.

Same as the File > Consolidate All Footage command. Footage items whose sources are identical (same file and interpretation, or same solid characteristics) are merged: layers referencing a duplicate are retargeted to the kept item, and the duplicate is removed.

Returns:

int –

The total number of footage items removed.

import_file ¶

import_file(
    options: ImportOptions,
) -> FootageItem | CompItem

Imports the file specified in the specified ImportOptions object, using the specified options. Same as the File > Import File command.

For ImportAsType.FOOTAGE, creates and returns a new FootageItem. For ImportAsType.COMP on a layered Illustrator/PDF (.ai, .pdf) or Photoshop (.psd, .psb) file, creates a composition with one footage layer per source layer (each referencing the same file) and returns that CompItem. For ImportAsType.COMP_CROPPED_LAYERS on an SVG, converts the vector artwork into a new composition holding a single shape layer and returns that CompItem (unlike ExtendScript, where importFile returns null for an SVG).

Parameters:

options (ImportOptions) –

The import settings. ImportAsType.FOOTAGE, COMP (layered .ai/.pdf/.psd/.psb), and (for SVG) COMP_CROPPED_LAYERS are supported. With ImportOptions.layer_index set (py_aep extension mirroring the "Choose Layer" option of AE's import dialog), a FOOTAGE import of a layered file references that single layer instead of the merged/whole document; see also ImportOptions.layer_dimensions and py_aep.list_layers.

Returns:

FootageItem | CompItem –

The newly created FootageItem or CompItem.

Raises:

ValueError –

If import_as is unsupported for the file, or the file extension is not a supported format.
NotImplementedError –

If media-header probing is not implemented for the file's format.
UnsupportedSVGError –

If the SVG uses features py_aep cannot import.
UnsupportedAiLayersError –

If a layered .ai/.pdf import is requested but the file exposes no PDF Optional Content Groups (e.g. saved without PDF compatibility).
UnsupportedPsdLayersError –

If a .psd/.psb COMP import is requested but the file is not a valid Photoshop document.

import_placeholder ¶

import_placeholder(
    name: str | None,
    width: int,
    height: int,
    frame_rate: float,
    duration: float,
) -> FootageItem

Import a placeholder footage item into the project root folder.

Parameters:

name (str | None) –

The placeholder name. Pass None to use Missing Name. An empty string becomes Placeholder.
width (int) –

Width in pixels (4-30000).
height (int) –

Height in pixels (4-30000).
frame_rate (float) –

Frame rate in fps (1.0-99.0).
duration (float) –

Duration in seconds (> 0, <= 10800).

Returns:

FootageItem –

The newly created FootageItem.

layer_by_id ¶

layer_by_id(layer_id: int) -> Layer

Get a layer by its unique ID.

list_color_profiles ¶

list_color_profiles() -> list[str]

Return the color-space names assignable in the current CMS mode.

These are the names valid for working_space (and, in Adobe mode, [media_color_space][ py_aep.models.sources.footage.FootageSource.media_color_space] and the output color space).

Adobe CMS: the catalogued Adobe ICC profile names.
OCIO: the active color spaces of ocio_configuration_file (a .ocio path or a built-in name like "ACES 1.2"). Returns [] if the config cannot be located or read.

reduce_project ¶

reduce_project(items_to_keep: list[Item]) -> int

Remove all items except those specified and the items they use.

Same as the File > Reduce Project command. For each kept composition, the items it uses (and their dependencies, recursively) are also kept. The folders containing kept items are kept as well.

Parameters:

items_to_keep (list[Item]) –

The items to keep in the project.

Returns:

int –

The total number of items removed.

remove_unused_footage ¶

remove_unused_footage() -> int

Remove footage items that are not used in any composition.

Same as the File > Remove Unused Footage command.

Returns:

int –

The total number of footage items removed.

replace_font ¶

replace_font(
    from_font: FontObject | str,
    to_font: FontObject | str,
    no_font_locking: bool = False,
) -> bool

Replace all usages of from_font with to_font.

A complete and precise replacement, even on text documents with mixed styling: the character ranges from_font was applied to are preserved, and every source-text keyframe of every text layer is covered. This operation is not undoable.

Each font may be given as a FontObject (e.g. from used_fonts) or as a PostScript name.

Parameters:

from_font (FontObject | str) –

Font to be replaced.
to_font (FontObject | str) –

Font to replace it with.
no_font_locking (bool, default: False ) –

Accepted for ExtendScript parity and ignored. After Effects uses it to suppress the fallback font it picks when to_font lacks glyphs for the text; that fallback is a runtime font-engine decision py_aep does not make, so py_aep always performs the direct replacement (i.e. it behaves as if this were True).

Returns:

bool –

True if at least one layer was changed.

save ¶

save(path: PathLike[str]) -> None

Save the project to a new .aep file at the given path.

Warning

This is highly experimental for now.

Raises:

FileExistsError –

If path already exists; overwriting is not allowed while saving is experimental.