Footage

FootageItem ¶

Bases: AVItem

The FootageItem object represents a footage item imported into a project, which appears in the Project panel.

Example

from py_aep import parse

app = parse("project.aep")
footage = app.project.footages[0]
print(footage.main_source)

Info

FootageItem is a subclass of AVItem object, which is a subclass of Item object. All methods and attributes of AVItem and Item are available when working with FootageItem.

See: https://ae-scripting.docsforadobe.dev/item/footageitem/

Attributes¶

asset_type ¶

asset_type: str

The footage type (placeholder, solid, file). Read-only.

comment ¶

comment: str

The item comment. Read / Write.

duration ¶

duration: float

The duration of the item in seconds. Still footages have a duration of 0. Read-only.

dynamic_link_guid ¶

dynamic_link_guid: str

A unique and persistent identification number used for the dynamic link, in form of 00000000-0000-0000-0000-000000000000. Read-only.

end_frame ¶

end_frame: int

The footage end frame. Read-only.

file ¶

file: str | None

The footage file path if its source is a FileSource, else None.

footage_missing ¶

footage_missing: bool

When True, the AVItem is a placeholder, or represents footage with a source file that could not be found when the project was last saved.

In this case, the path of the missing source file is in the missing_footage_path attribute of the footage item's source-file object. See FootageItem.main_source and FileSource.missing_footage_path. Read-only.

frame_duration ¶

frame_duration: int

The duration of the item in frames. Still footages have a duration of 0. Read-only.

frame_rate ¶

frame_rate: float

The frame rate of the item in frames-per-second. Read-only.

frame_time ¶

frame_time: int

The current time of the item when it is being previewed directly from the Project panel. This value is a number of frames.

guides ¶

guides: list[Guide]

The item's ruler guides. Each guide has an orientation and a pixel position. Read-only.

has_audio ¶

has_audio: bool

When True, the footage has an audio component.

When use_proxy is True, reflects the proxy source rather than the main source. Read-only.

has_video ¶

has_video: bool

True if the item has a video component.

An AVItem has video when it has non-zero dimensions (width > 0 and height > 0). In a CompItem, the value is always True. In a FootageItem, the value depends on the footage source (e.g. audio-only files return False).

height ¶

height: int

The height of the item in pixels. Read-only.

id ¶

id = ChunkField[int](
    "_idta", "item_id", read_only=True, default=0
)

The item unique identifier. Read-only.

is_media_replacement_compatible ¶

is_media_replacement_compatible: bool

True if the footage can be used as an alternate source when setting Property.alternate_source. Read-only.

False for solids, for footage without a video component (audio-only or data files), and for 3D model scenes (AE 2026 reports an imported .fbx as incompatible even though it has video).

label ¶

label = enum(Label, '_idta', 'label', default=NONE)

The label color. Colors are represented by their number (0 for None, or 1 to 16 for one of the preset colors in the Labels preferences). Read / Write.

main_source ¶

main_source: FileSource | SolidSource | PlaceholderSource

The footage source. Read-only.

name ¶

name = ChunkField[str](
    "_name_utf8", "value", validate=validate_name
)

The name of the item, as shown in the Project panel. Read / Write.

parent_folder ¶

parent_folder: FolderItem | None

The parent folder of this item. None for the root folder. Read / Write.

Setting this moves the item into another folder. The item's binary chunk block is relocated from the old folder's container to the end of the new folder's container, and both folders' items lists are updated.

Raises:

ValueError –

If this is the root folder, or if moving a folder into itself or one of its own descendants.
TypeError –

If the value is not a FolderItem.

pixel_aspect ¶

pixel_aspect: float

The pixel aspect ratio of the item (1.0 is square). Read-only.

proxy_source ¶

proxy_source: (
    FileSource | SolidSource | PlaceholderSource | None
)

The FootageSource being used as a proxy. Read-only.

To change it, call any of the AVItem methods that change the proxy source: set_proxy(), set_proxy_with_sequence(), set_proxy_with_solid(), or set_proxy_with_placeholder().

selected ¶

selected: bool

When True, this item is selected. Read-only.

Note

Item selection is not stored in the .aep binary format; it is a runtime-only state. Parsed projects always report False.

start_frame ¶

start_frame: int

The footage start frame. Read-only.

time ¶

time: float

The current time of the item when it is being previewed directly from the Project panel. This value is a number of seconds. It is an error to set this value for a FootageItem whose main_source or proxy_source is still.

type_name ¶

type_name: str

A user-readable name for the item type ("Folder", "Footage" or "Composition"). These names are application locale-dependent, meaning that they are different depending on the application's UI language. Read-only.

use_proxy ¶

use_proxy = bool(
    "_idta",
    "use_proxy",
    validate=_validate_use_proxy,
    post_set=_sync_proxy_active,
)

When True, a proxy is used for the item. Read / Write.

It is set to True by all the set_proxy methods, and to False by the set_proxy_to_none() method.

used_in ¶

used_in: list[CompItem]

All the compositions that use this AVItem.

width ¶

width: int

The width of the item in pixels. Read-only.

Functions¶

add_guide ¶

add_guide(orientation_type: int, position: int) -> int

Adds a new guide to the item.

Any orientation_type value other than 0 (horizontal) or 1 (vertical) defaults to horizontal.

Parameters:

orientation_type (int) –

0 for horizontal, 1 for vertical.
position (int) –

The pixel position of the guide.

Returns:

int –

The index of the new guide.

remove ¶

remove() -> None

Remove this AV item, its referencing layers, and viewer.

remove_all_guides ¶

remove_all_guides() -> None

Remove all guides from the item.

Equivalent to calling remove_guide for each guide. A no-op when the item has no guides.

remove_guide ¶

remove_guide(guide_index: int) -> None

Removes an existing guide by index.

Parameters:

guide_index (int) –

The 0-based index of the guide to remove.

Raises:

IndexError –

If guide_index is out of range.

replace ¶

replace(
    file: str | PathLike[str],
    layer_index: int | _CurrentValue | None = None,
    layer_dimensions: str | _CurrentValue = CURRENT_VALUE,
    layer_styles: str | _CurrentValue = CURRENT_VALUE,
) -> None

Replace the footage source with a file on disk.

Changes the source of this FootageItem to the specified file.

In addition to loading the file, the method creates a new FileSource object for the file and sets main_source to that object. In the new source object, it sets the name, width, height, frame_duration, and duration attributes (see AVItem object) based on the contents of the file.

The method preserves interpretation parameters from the previous main_source object.

py_aep extension: layer_index binds the new source to a single layer of a layered file, by list_layers position (see ImportOptions.layer_index). None (the default) always replaces with the merged/whole document, even when the current source references a single layer - consistent with import_file, where layer_index=None imports merged. Pass CURRENT_VALUE to rebind at the current source's stored layer index (the sspc layer index: PSD record index / AI document index) in the new file.

layer_dimensions chooses the footage dimensions when a layer is selected (see ImportOptions.layer_dimensions): "document" (the full canvas) or "layer" (the layer's content box). CURRENT_VALUE (the default) preserves the current single-layer binding's choice. Layer Size is only representable for PSD targets - AI/PDF always use Document size, and "layer" on an AI/PDF file raises NotImplementedError. layer_dimensions is ignored when layer_index is None (a merged document is always document-sized).

layer_styles chooses how a PSD layer's styles are treated (see ImportOptions.layer_styles): "merge" (bake them into the raster, AE's dialog default) or "ignore". CURRENT_VALUE (the default) preserves the current binding's recorded choice verbatim - including the "editable" marker of an editable-comp per-layer footage item, which is not accepted as an explicit argument (AE's footage dialog offers merge/ignore only) - and falls back to "merge" when the current source has no PSD layer binding. Like layer_dimensions, it is ignored when layer_index is None.

Note

Unlike ExtendScript, if the specified file has an unlabeled alpha channel, this method does not estimate the alpha interpretation.

Parameters:

file (str | PathLike[str]) –

Path to the new source file.
layer_index (int | _CurrentValue | None, default: None ) –

Layer of the new file to reference, as its 0-based list_layers position, or CURRENT_VALUE (layered files only); None replaces with the merged/whole document.
layer_dimensions (str | _CurrentValue, default: CURRENT_VALUE ) –

"document", "layer", or CURRENT_VALUE to keep the current binding's choice (the default).
layer_styles (str | _CurrentValue, default: CURRENT_VALUE ) –

"merge", "ignore", or CURRENT_VALUE to keep the current binding's choice (the default). PSD targets only.

Raises:

ValueError –

If the extension is not a supported footage format, if layer_index is passed for a non-layered file, if layer_index is out of range for the new file, if layer_dimensions is not "document"/"layer"/CURRENT_VALUE, if layer_styles is not "merge"/"ignore"/CURRENT_VALUE or is passed explicitly for an AI/PDF target, or if CURRENT_VALUE is passed while the current source does not reference a single layer (or the new file has no layer at the stored index).
NotImplementedError –

If After Effects requires a format-specific opti header not implemented for this format, if layer_dimensions="layer" is requested for an AI/PDF file, or if layer_dimensions="layer" is combined with merge-mode styles on a PSD layer that has styles (the style-expanded bounds are not derivable).

replace_with_placeholder ¶

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

Replace the footage source with a placeholder.

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

replace_with_sequence ¶

replace_with_sequence(
    file: str | PathLike[str],
    force_alphabetical: bool = False,
) -> None

Changes the source of this FootageItem to the specified image sequence.

In addition to loading the file, the method creates a new FileSource object for the file and sets main_source to that object. In the new source object, it sets the name, width, height, frame_duration, and duration attributes (see AVItem object) based on the contents of the file.

The method preserves interpretation parameters from the previous main_source object.

Note

Unlike ExtendScript, if the specified file has an unlabeled alpha channel, this method does not estimate the alpha interpretation.

Parameters:

file (str | PathLike[str]) –

Path to a representative frame; sibling frames in the same folder are gathered into the sequence.
force_alphabetical (bool, default: False ) –

Order frames alphabetically rather than numerically.

Raises:

ValueError –

If the extension is not a supported footage format.
NotImplementedError –

If After Effects requires a format-specific opti header not implemented for this format.

replace_with_solid ¶

replace_with_solid(
    color: list[float],
    name: str | None,
    width: int,
    height: int,
    pixel_aspect: float = 1.0,
) -> None

Replace the footage source with a solid.

Parameters:

color (list[float]) –

Solid color as [R, G, B] in 0.0-1.0 range.
name (str | None) –

The solid name. Pass None to auto-generate a name from the color (e.g. Red Solid 1). An empty string becomes ????.
width (int) –

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

Height in pixels (1-30000).
pixel_aspect (float, default: 1.0 ) –

Pixel aspect ratio (0.01-100.0).

set_proxy ¶

set_proxy(file: str | PathLike[str]) -> None

Sets a file as the proxy of this AVItem.

Loads the specified file into a new FileSource object, sets this as the value of the proxy_source attribute, and sets use_proxy to true.

It does not preserve the interpretation parameters, instead using the user preferences.

This differs from setting a FootageItem's main_source, but both actions are performed as in the user interface.

Note

Unlike ExtendScript, if the specified file has an unlabeled alpha channel, this method does not estimate the alpha interpretation.

Parameters:

file (str | PathLike[str]) –

Path to the proxy source file.

Raises:

ValueError –

If the extension is not a supported footage format.
NotImplementedError –

If After Effects requires a format-specific opti header not implemented for this format.

set_proxy_to_none ¶

set_proxy_to_none() -> None

Remove the proxy source from this item.

set_proxy_with_placeholder ¶

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

Set a placeholder as the proxy source.

Parameters:

name (str | None) –

The placeholder name. None becomes 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).

set_proxy_with_sequence ¶

set_proxy_with_sequence(
    file: str | PathLike[str],
    force_alphabetical: bool = False,
) -> None

Sets a sequence of files as the proxy of this AVItem, with the option of forcing alphabetical order. Loads the specified file sequence into a new FileSource object, sets this as the value of the proxy_source attribute, and sets use_proxy to true.

It does not preserve the interpretation parameters, instead using the user preferences.

Note

Unlike ExtendScript, if the specified file has an unlabeled alpha channel, this method does not estimate the alpha interpretation.

Parameters:

file (str | PathLike[str]) –

Path to a representative frame; sibling frames in the same folder are gathered into the sequence.
force_alphabetical (bool, default: False ) –

Order frames alphabetically rather than numerically.

Raises:

ValueError –

If the extension is not a supported footage format.
NotImplementedError –

If After Effects requires a format-specific opti header not implemented for this format.

set_proxy_with_solid ¶

set_proxy_with_solid(
    color: list[float],
    name: str | None,
    width: int,
    height: int,
    pixel_aspect: float = 1.0,
) -> None

Set a solid as the proxy source.

Parameters:

color (list[float]) –

Solid color as [R, G, B] in 0.0-1.0 range.
name (str | None) –

The solid name. Pass None to auto-generate a name from the color (e.g. Red Solid 1). An empty string becomes ????.
width (int) –

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

Height in pixels (1-30000).
pixel_aspect (float, default: 1.0 ) –

Pixel aspect ratio (0.01-100.0).