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

The binary chunk stores both the profile name and embedded ICC or OCIO color-space data (base64-encoded). Changing the name alone would leave stale profile data. See working_space for details.

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.

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

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", "None"). Read-only.

The binary chunk stores both the profile name and its full ICC profile data (base64-encoded). Changing the name alone would leave stale ICC data, producing a file that After Effects may reject or silently revert. Generating the ICC data would require the Adobe ICC profile files installed on disk, which cannot be assumed.

xmp_packet ¶

xmp_packet = ChunkField[Element](
    "_aep",
    "_xmp",
    transform=fromstring,
    reverse=lambda el: tostring(el, encoding="unicode"),
)

The XMP packet for the project, containing metadata. 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

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

Creates and returns a new FootageItem object from the file, and adds it to the project's items array.

Parameters:

options (ImportOptions) –

The import settings. Only ImportAsType.FOOTAGE is supported.

Returns:

FootageItem –

The newly created FootageItem.

Raises:

ValueError –

If import_as is not ImportAsType.FOOTAGE, or the file extension is not a supported footage format.
NotImplementedError –

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

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.

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.