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.

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.

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

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