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

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

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",
    reverse_instance_field=lambda value, _body: {
        "frames_count_type": value
    },
    validate=validate_one_of((0, 1)),
)

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.

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

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

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",
    invalidates=["display_start_frame"],
)

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

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

gpu_accel_type ¶

gpu_accel_type = ChunkField[Any](
    "_gpug_utf8",
    "contents",
    transform=lambda contents: from_binary(
        strip_null(contents)
    ),
    reverse_seq_field=to_binary,
)

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

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

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

working_gamma ¶

working_gamma = ChunkField[float](
    "_dwga",
    "working_gamma",
    reverse_instance_field=_reverse_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_packet",
    transform=fromstring,
    reverse_seq_field=lambda el: tostring(
        el, encoding="unicode"
    ),
)

The XMP packet for the project, containing metadata. Read / Write.

Functions¶

layer_by_id ¶

layer_by_id(layer_id: int) -> Layer

Get a layer by its unique ID.

save ¶

save(path: Path) -> None

Save the project to a new .aep file at the given path. As writing is still experimental, overwriting is not allowed for now.

Warning

This is highly experimental for now.