Text document

TextDocument ¶

Stores a value for a TextLayer's Source Text property.

Example

from py_aep import parse

app = parse("project.aep")
comp = app.project.compositions[0]
text_doc = comp.text_layers[0].text.source_text.value
print(text_doc.text)

See: https://ae-scripting.docsforadobe.dev/text/textdocument/

Attributes¶

all_caps ¶

all_caps: bool | None

True if a Text layer has All Caps enabled. Read-only.

apply_fill ¶

apply_fill = bool('_char_style', '56', default=None)

When True, the Text layer shows a fill. Read / Write.

apply_stroke ¶

apply_stroke = bool('_char_style', '57', default=False)

When True, the Text layer shows a stroke. Read / Write.

auto_hyphenate ¶

auto_hyphenate = bool('_para_style', '9', default=None)

The Text layer's auto hyphenate option. Read / Write.

auto_kern_type ¶

auto_kern_type: AutoKernType | None

The Text layer's auto kern type option. Read / Write.

Setting a non-manual kern type also clears the manual kerning values document-wide, dropping the kern-run array and the leading-edge value like the range setter (probed X_AKT_SET).

auto_leading ¶

auto_leading: bool | None

The Text layer's auto leading option. Read / Write.

Enabling auto-leading also resets the explicit leading key to AE's sentinel across the document (probed X_AL_SET).

baseline_direction ¶

baseline_direction = enum(
    BaselineDirection,
    "_char_style",
    "35",
    default=BASELINE_WITH_STREAM,
)

The Text layer's baseline direction. Read / Write.

baseline_locs ¶

baseline_locs: list[float]

The baseline (x,y) locations for a Text layer. Line wraps in a paragraph text box are treated as multiple lines. Read-only.

Four floats per composed line - line.start_x, line.start_y, line.end_x, line.end_y - in layer coordinates. Empty for documents never parsed from a layer or without a layout cache.

Tip

If a line has no characters, the x and y values for start and end are the maximum float value (3.402823466e+38).

Note

Unlike composed_line_count, this always reports the layout After Effects persisted: the per-line pen origins and glyph advances only exist in that cache, and the composed-line resolver does not reproduce them. After a layout-affecting py-side write the values therefore stay at the persisted layout even when the resolver could recompose the line spans (see composition_stale).

baseline_shift ¶

baseline_shift = float(
    "_char_style",
    "9",
    default=None,
    validate=validate_number,
)

This Text layer's baseline shift in pixels. Read / Write.

box_auto_fit_policy ¶

box_auto_fit_policy: BoxAutoFitPolicy

The box's auto-fit policy. Read / Write.

box_first_baseline_alignment ¶

box_first_baseline_alignment: BoxFirstBaselineAlignment

The box's first-baseline alignment. Read / Write.

box_first_baseline_alignment_minimum ¶

box_first_baseline_alignment_minimum: float

The minimum for MINIMUM_VALUE_* first-baseline alignment. R/W.

box_inset_spacing ¶

box_inset_spacing: float

The box's inset (padding) spacing in pixels. Read / Write.

box_overflow ¶

box_overflow: bool | None

True if the text overflows the box. Read-only.

A composition covers fewer characters than the stored text exactly when the text overflows (probed via samples/models/text/box_overflow.aep). Reads the persisted AE cache while the document is untouched and the calibrated composer after layout-affecting py-side writes (see composition_stale). None for point text (ExtendScript reads undefined there) and for documents without a cache.

box_text ¶

box_text: bool

True if this is a box (paragraph) text layer. Read-only.

Box text stores the bounding-box vertex array in the frame; point text omits it.

box_text_pos ¶

box_text_pos: list[float] | None

The top-left position of the text box as [x, y]. Read / Write.

None for point text. Setting moves the box while keeping its size; requires box (paragraph) text.

box_text_size ¶

box_text_size: list[float] | None

The size of the text box as [width, height]. Read / Write.

None for point text. Setting dimensions on point text converts it into a box (paragraph) text layer; on box text it resizes the box while keeping its top-left corner fixed.

box_vertical_alignment ¶

box_vertical_alignment: BoxVerticalAlignment

The box's vertical text alignment. Read / Write.

composed_line_count ¶

composed_line_count: int | None

The number of composed lines in the Text layer. Read-only.

Point text derives its lines from the paragraphs (always fresh). Box text reads the layout cache AE persisted at save time; after a layout-affecting py-side write the calibrated composed-line resolver recomposes it, otherwise the cached count stays (matching ExtendScript's un-reapplied values - see composition_stale). None for documents never parsed from a layer.

composed_line_ranges ¶

composed_line_ranges: list[dict[str, int]]

Character bounds of every composed line as {"start", "end"} records. Read-only.

Matches composed_line_range bounds (ends clamped to the visible text, stale cached lines beyond it dropped) from one span derivation; empty for documents never parsed from a layer or without a layout cache. Like the other composed-line APIs, recomposes freshly when the calibrated composer covers the document, otherwise reflects the composition AE last persisted.

composer_engine ¶

composer_engine: ComposerEngine | None

The Text layer's composer engine type. Read-only.

composition_stale ¶

composition_stale: bool

True when the composed-line APIs may not reflect this document's current content. Read-only.

Point text is never stale (its composed lines are the paragraphs). Box text goes stale after a layout-affecting py-side write unless the composed-line resolver calibrated against this document's own persisted cache and can recompose its current state (see the resolvers.text_composition module).

The flag tracks writes made through THIS document object: a document re-parsed from a py-written file, or minted by Layer.duplicate, starts clean even when its persisted cache no longer matches its text.

digit_set ¶

digit_set = enum(
    DigitSet, "_char_style", "70", default=DEFAULT_DIGITS
)

The Text layer's digit set option. Read / Write.

direction ¶

direction = enum(
    ParagraphDirection,
    "_para_style",
    "33",
    default=DIRECTION_LEFT_TO_RIGHT,
)

The Text layer's paragraph direction. Read / Write.

end_indent ¶

end_indent = float(
    "_para_style",
    "3",
    default=0.0,
    validate=validate_number,
)

The Text layer's paragraph end indent. Read / Write.

every_line_composer ¶

every_line_composer = bool(
    "_para_style", "29", default=False
)

The Text layer's Every-Line Composer option. Read / Write.

True when Every-Line Composer is used, False for Single-Line.

faux_bold ¶

faux_bold = bool('_char_style', '2', default=None)

True if a Text layer has faux bold enabled. Read / Write.

faux_italic ¶

faux_italic = bool('_char_style', '3', default=None)

True if a Text layer has faux italic enabled. Read / Write.

fill_color ¶

fill_color: list[float] | None

The Text layer's fill color as [r, g, b]. Read / Write.

first_line_indent ¶

first_line_indent = float(
    "_para_style",
    "1",
    default=0.0,
    validate=validate_number,
)

The Text layer's paragraph first line indent. Read / Write.

font ¶

font: str | None

The Text layer's font PostScript name. Read / Write.

font_baseline_option ¶

font_baseline_option = enum(
    FontBaselineOption, "_char_style", "13", default=None
)

The Text layer's font baseline option. Read / Write.

font_caps_option ¶

font_caps_option = enum(
    FontCapsOption, "_char_style", "12", default=None
)

The Text layer's font caps option. Read / Write.

font_object ¶

font_object: FontObject | None

The Text layer's FontObject. Read-only.

font_size ¶

font_size = float(
    "_char_style",
    "1",
    default=None,
    validate=validate_positive_nonzero_number,
)

The Text layer's font size in pixels. Read / Write.

hanging_roman ¶

hanging_roman = bool('_para_style', '21', default=False)

The Text layer's Roman Hanging Punctuation. Read / Write.

horizontal_scale ¶

horizontal_scale = float(
    "_char_style",
    "6",
    default=None,
    validate=validate_number,
)

This Text layer's horizontal scale in pixels. Read / Write.

justification ¶

justification = enum(
    ParagraphJustification, "_para_style", "0", default=None
)

The paragraph justification for the Text layer. Read / Write.

kerning ¶

kerning: int

The Text layer's kerning value. Read-only.

Reads the leading-edge manual kern value AE stores at doc["0"]["7"] - written only when a kerning set includes pair position 0 (probed W_KERN_START). Documents without one read 0, which is also what ExtendScript exports for every probed document-level read; per-character values live in the kerning runs via character_range(...).kerning.

leading ¶

leading: float | None

The Text layer's spacing between lines. Read / Write.

When auto-leading is enabled, returns font_size * auto_leading_factor.

leading_type ¶

leading_type = enum(
    LeadingType,
    "_para_style",
    "8",
    default=ROMAN_LEADING_TYPE,
)

The Text layer's paragraph leading type. Read / Write.

ligature ¶

ligature = bool('_char_style', '18', default=False)

When True, ligature is used. Read / Write.

line_join_type ¶

line_join_type = enum(
    LineJoinType,
    "_char_style",
    "62",
    default=LINE_JOIN_MITER,
)

The Text layer's line join type for strokes. Read / Write.

line_orientation ¶

line_orientation: LineOrientation

The Text layer's line orientation. Read / Write.

no_break ¶

no_break = bool('_char_style', '52', default=False)

When True, the no-break attribute is applied. Read / Write.

paragraph_count ¶

paragraph_count: int | None

The number of paragraphs in the text layer. Read-only.

paragraph_ranges ¶

paragraph_ranges: list[dict[str, int]]

Character bounds of every paragraph as {"start", "end"} records. Read-only.

Matches paragraph_range bounds (paragraph spans clamped to the visible text) from one pass over the paragraph runs; empty for documents never parsed from a layer. Ground-truth validation compares this against ExtendScript's per-paragraph dump.

point_text ¶

point_text: bool

True if this is a point text layer. Read-only.

small_caps ¶

small_caps: bool | None

True if a Text layer has Small Caps enabled. Read-only.

space_after ¶

space_after = float(
    "_para_style",
    "5",
    default=0.0,
    validate=validate_number,
)

The Text layer's paragraph space after. Read / Write.

space_before ¶

space_before = float(
    "_para_style",
    "4",
    default=0.0,
    validate=validate_number,
)

The Text layer's paragraph space before. Read / Write.

start_indent ¶

start_indent = float(
    "_para_style",
    "2",
    default=0.0,
    validate=validate_number,
)

The Text layer's paragraph start indent. Read / Write.

stroke_color ¶

stroke_color: list[float] | None

The Text layer's stroke color as [r, g, b]. Read / Write.

stroke_over_fill ¶

stroke_over_fill = bool('_char_style', '58', default=True)

When True, the stroke appears over the fill. Read / Write.

stroke_width ¶

stroke_width = float(
    "_char_style",
    "63",
    default=1.0,
    validate=validate_positive_nonzero_number,
)

The Text layer's stroke thickness in pixels. Read / Write.

subscript ¶

subscript: bool | None

True if a Text layer has subscript enabled. Read-only.

superscript ¶

superscript: bool | None

True if a Text layer has superscript enabled. Read-only.

text ¶

text: str

The text value for the Source Text property. Read / Write.

tracking ¶

tracking = int(
    "_char_style", "8", default=None, validate=validate_s4
)

The Text layer's spacing between characters. Read / Write.

tsume ¶

tsume = float(
    "_char_style",
    "36",
    default=0.0,
    validate=validate_normalized_float,
)

This Text layer's tsume value (0.0 to 1.0). Read / Write.

vertical_scale ¶

vertical_scale = float(
    "_char_style",
    "7",
    default=None,
    validate=validate_number,
)

This Text layer's vertical scale in pixels. Read / Write.

Functions¶

character_range ¶

character_range(
    character_start: int,
    signed_character_end: int | None = None,
) -> CharacterRange

A CharacterRange over part of this document.

Parameters:

character_start (int) –

First character index (UTF-16 units, 0 <= character_start <= text length).
signed_character_end (int | None, default: None ) –

Index past the last character. -1 resolves dynamically to the text length; when omitted, defaults to character_start + 1.

Raises:

ValueError –

When the indices are outside the document bounds (AE raises at creation time).

composed_line_character_indexes_at ¶

composed_line_character_indexes_at(
    character_index: int,
) -> dict[str, int]

The character bounds of the composed line containing an index.

Parameters:

character_index (int) –

A character index (UTF-16 units) within the text.

Returns:

dict[str, int] –

{"start": int, "end": int} for the containing composed line.

Raises:

ValueError –

When character_index is outside the text or the document has no composed-line cache.

composed_line_range ¶

composed_line_range(
    composed_line_index_start: int,
    signed_composed_line_index_end: int | None = None,
) -> ComposedLineRange

A ComposedLineRange over part of this document.

Composed lines come from the layout cache AE persisted at save time, or from the calibrated composed-line resolver after py-side edits; see ComposedLineRange for the semantics.

Parameters:

composed_line_index_start (int) –

First composed-line index (0 <= composed_line_index_start < composed line count).
signed_composed_line_index_end (int | None, default: None ) –

Index past the last line. -1 resolves dynamically to the line count; when omitted, defaults to composed_line_index_start + 1.

Raises:

ValueError –

When the indices are outside the cached composed lines (AE raises at creation time).

paragraph_character_indexes_at ¶

paragraph_character_indexes_at(
    character_index: int,
) -> dict[str, int]

The character bounds of the paragraph containing an index.

Parameters:

character_index (int) –

A character index (UTF-16 units) within the text.

Returns:

dict[str, int] –

{"start": int, "end": int} for the containing paragraph.

Raises:

ValueError –

When character_index is outside the text.

paragraph_range ¶

paragraph_range(
    paragraph_index_start: int,
    signed_paragraph_index_end: int | None = None,
) -> ParagraphRange

A ParagraphRange over part of this document.

Parameters:

paragraph_index_start (int) –

First paragraph index (0 <= paragraph_index_start < paragraph count).
signed_paragraph_index_end (int | None, default: None ) –

Index past the last paragraph. -1 resolves dynamically to the paragraph count; when omitted, defaults to paragraph_index_start + 1.

Raises:

ValueError –

When the indices are outside the document bounds (AE raises at creation time).

reset_char_style ¶

reset_char_style() -> None

Restores all characters in the Text layer to the default text character characteristics in the Character panel.

After Effects applies its Character-panel defaults, which live in the AE preferences rather than the project file (the ["Text Style Sheet"] section - the same values addText gives a new layer). py_aep reads them from the preferences directory the project was parsed with, and falls back to AE's factory values when no preference file is available.

Note

Attributes the Character panel does not carry are left alone, matching After Effects.

Raises:

ValueError –

If the document was never associated with a layer.

reset_paragraph_style ¶

reset_paragraph_style() -> None

Restores all paragraphs in the Text layer to the default text paragraph characteristics in the Paragraph panel.

After Effects applies its Paragraph-panel defaults, which live in the AE preferences rather than the project file (the ["Text Paragraph Sheet"] section). py_aep reads them from the preferences directory the project was parsed with, and falls back to AE's factory values when no preference file is available.

Note

Hyphenation has no entry in that sheet, so - like After Effects - this leaves auto_hyphenate untouched.

Raises:

ValueError –

If the document was never associated with a layer.