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 = ChunkField[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 = ChunkField[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 = ChunkField[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.

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 an OCIO color-space name rewrites the embedded profile JSON (AE identifies it by name, no ICC data). 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¶

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.

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.