File source

FileSource ¶

Bases: FootageSource

The FileSource object describes footage that comes from a file.

Example

from py_aep import FileSource, parse

app = parse("project.aep")
footage = app.project.footages[0]
if isinstance(footage.main_source, FileSource):
    print(footage.main_source.file)

Info

FileSource is a subclass of FootageSource object. All methods and attributes of FootageSource are available when working with FileSource.

See: https://ae-scripting.docsforadobe.dev/sources/filesource/

Attributes¶

alpha_mode ¶

alpha_mode = enum(AlphaMode, '_sspc', 'alpha_mode_raw')

Defines how the alpha information in the footage is interpreted. If has_alpha is False, this attribute has no relevant meaning. Read / Write.

conform_frame_rate ¶

conform_frame_rate = ChunkField[float](
    "_sspc",
    "conform_frame_rate",
    validate=_validate_number(min=0.0, max=999.0),
)

A frame rate to use instead of the native_frame_rate value. If set to 0, the native_frame_rate is used instead. Read / Write.

display_frame_rate ¶

display_frame_rate = ChunkField[float](
    "_sspc", "display_frame_rate", read_only=True
)

The effective frame rate as displayed and rendered in compositions. If remove_pulldown is active, the rate is multiplied by 0.8. Read-only.

field_separation_type ¶

field_separation_type = enum(
    FieldSeparationType, "_sspc", "field_separation_type"
)

How the fields are to be separated in non-still footage. Read / Write.

file ¶

file: str

The full file path. Read-only.

file_attributes ¶

file_attributes: dict[str, int | str]

Format-specific metadata extracted from the source file header stored in the project.

For PSD (Photoshop) sources, the following keys are available:

psd_layer_index (int): Zero-based index of this layer within the PSD file. 0xFFFFFFFF means merged/flattened.
psd_group_name (str): PSD group/folder that contains this layer (e.g. "PAINT 02").
psd_layer_count (int): Total number of layers in the source PSD.
psd_canvas_width (int): Full PSD canvas width in pixels.
psd_canvas_height (int): Full PSD canvas height in pixels.
psd_bit_depth (int): Bit depth per channel (8, 16, 32).
psd_channels (int): Number of color channels (3 for RGB, 4 for RGBA/CMYK).
psd_layer_top (int): Layer bounding-box top (pixels, can be negative if the layer extends above the canvas).
psd_layer_left (int): Layer bounding-box left.
psd_layer_bottom (int): Layer bounding-box bottom.
psd_layer_right (int): Layer bounding-box right.

Read-only.

file_names ¶

file_names: list[str]

The filenames if the footage is an image sequence. Read-only.

has_alpha ¶

has_alpha = ChunkField[bool](
    "_sspc", "has_alpha", read_only=True
)

When True, the footage has an alpha component. In this case, the attributes alpha_mode, invert_alpha, and premultiplied have valid values. When False, those attributes have no relevant meaning for the footage. Read-only.

high_quality_field_separation ¶

high_quality_field_separation = bool(
    "_sspc",
    "high_quality_field_separation",
    transform=lambda v: v % 2 != 0,
    reverse=int,
)

When True, After Effects uses special algorithms to determine how to perform high-quality field separation. Read / Write.

interpret_as_linear_light ¶

interpret_as_linear_light = enum(
    LinearLightMode, "_linl", "value", default=OFF
)

The Interpret As Linear Light setting from the Interpret Footage > Color Management tab. Read / Write.

Note

Not exposed in ExtendScript.

invert_alpha ¶

invert_alpha = bool('_sspc', 'invert_alpha')

When True, an alpha channel in a footage clip or proxy should be inverted. This attribute is valid only if an alpha is present. If has_alpha is False, or if alpha_mode is AlphaMode.IGNORE, this attribute is ignored. Read / Write.

is_still ¶

is_still: bool

When True the footage is still; When False, it has a time-based component. Read-only.

layer_name ¶

layer_name: str

The referenced layer's name when this source is a single layer of a layered file (a chosen-layer import or a member of a layered comp import), or an empty string for merged/whole-file footage. Read-only.

py_aep extension: ExtendScript exposes no layer-selection API.

layer_styles ¶

layer_styles: str | None

The layer-styles choice recorded for a Photoshop single-layer binding: "editable", "merge" or "ignore" (see ImportOptions.layer_styles), or None when this source is not a PSD single-layer binding (merged/whole-document footage, other formats). Read-only.

py_aep extension. "editable" appears on the per-layer footage of an Editable-Layer-Styles comp import; FootageItem.replace rejects it as an explicit argument (AE's footage dialog offers merge/ignore only) - CURRENT_VALUE is the way to preserve it. The byte encoding was pinned on AE 2026 output; on much older projects the reported value is whatever the byte says.

loop ¶

loop = ChunkField[int](
    "_sspc",
    "loop",
    validate=_validate_number(
        min=1, max=9999, integer=True
    ),
)

The number of times that the footage is to be played consecutively when used in a composition. Read / Write.

media_color_space ¶

media_color_space: str

The media color space from the Interpret Footage > Color Management tab. Read / Write.

Returns "Embedded", "Working Color Space", the name of an assigned OCIO color space, or the name of an Adobe ICC profile (e.g. "Apple RGB"). As with working_space, an assigned OCIO space reads back as AE's stored colorProfileName: "<family>/<name>" for a direct color-space pick (e.g. "ACES/ACES - ACEScg"), or the target name for a role/alias pick.

Writable: "Working Color Space", "Embedded", an Adobe ICC profile name, or - in OCIO mode - any color space, role, alias or display/view pair of the project's OCIO configuration (the "<family>/<name>" form this getter returns is accepted too). The config must be resolvable, since the envelope AE writes depends on which kind the name is. An Adobe profile is identified by its 16-byte ID and its ICC bytes are discovered on disk (ColorProfileNotFoundError if not installed).

Note

Assigning back what this getter returns is lossy for a ROLE pick. AE stores the role's TARGET, not the role, and many roles can share one target (ACES 1.2 points rendering, scene_linear and compositing_linear all at ACES - ACEScg), so which role was chosen is not recoverable from the file. Re-assigning the target name records a direct color-space pick instead - the same color transform, different bytes. Pass the role name (e.g. "matte_paint") to write a role pick.

Note

Not exposed in ExtendScript.

missing_footage_path ¶

missing_footage_path: str

The path of the missing source file when the footage was missing at the time the project was last saved, otherwise an empty string. Read-only.

native_frame_rate ¶

native_frame_rate = ChunkField[float](
    "_sspc", "native_frame_rate", read_only=True
)

The native frame rate of the footage. Read-only.

premul_color ¶

premul_color = ChunkField[List[float]](
    "_sspc", "premul_color", validate=validate_rgb_color
)

The color to be premultiplied. This attribute is valid only if the alpha_mode is AlphaMode.PREMULTIPLIED. Read / Write.

preserve_rgb ¶

preserve_rgb: bool

When True, the footage Preserve RGB setting is enabled. From the Interpret Footage > Color Management tab. Read / Write.

Note

Not exposed in ExtendScript.

remove_pulldown ¶

remove_pulldown = enum(
    PulldownPhase,
    "_sspc",
    "remove_pulldown",
    post_set="_on_remove_pulldown_set",
)

Controls which pulldown phase to remove from the source footage. PulldownPhase.OFF by default. Read / Write.

target_is_folder ¶

target_is_folder: bool

True if the file is a folder, else False. Read-only.

Functions¶

reload ¶

reload() -> None

Reloads the asset from the file.

Re-reads the media at the stored path and updates the cached source metadata in place - dimensions, alpha, frame rate, duration, pixel aspect, audio, cached data size, the format opti header and (for AI/EPS/PDF) the embedded color-profile record - like After Effects' File > Reload Footage (byte-validated against an AE 2026 reload of a still image whose file changed on disk). Image sequences re-scan their sibling frames; the item name is never changed.

Note

ExtendScript restricts reload() to a mainSource; py_aep also allows it on a proxySource. Every chunk it refreshes (sspc, opti, CLRS) lives in the source's own Pin, so a proxy reload is self-contained. The owning item's idta footage-kind flags are only refreshed for a mainSource - they describe the main source's kind, and AE keeps them pointing at it while a proxy is attached.

Raises:

ValueError –

If the stored path no longer exists or is no longer a file, or if its extension is not a supported footage format.
NotImplementedError –

If the format needs a format-specific opti header that is not implemented.