Component¶

class Component:
    """An effect (or intrinsic transform) applied to a track item.

    Only materialized components appear: Premiere synthesizes untouched
    intrinsics (Motion, Opacity, ...) at runtime and stores nothing for
    them.
    """

    def __init__(self, _element: ET.Element, track_item: TrackItem) -> None:
        self._element = _element
        self.track_item = track_item
        self._properties: list[ComponentParam] = []
        self._sub_components: list[Component] = []

    @property
    def display_name(self) -> str:
        """The component name. Read-only."""
        inner = self._inner()
        return (inner.findtext("DisplayName") or "") if inner is not None else ""

    @property
    def match_name(self) -> str:
        """The registry identifier. Read-only.

        Video components store this as `MatchName`; audio filter components
        store it as `FilterMatchName` (e.g. `Internal Volume Mono`), which
        ExtendScript also reports as the match name.
        """
        match = self._element.findtext("MatchName")
        if match:
            return match
        return self._element.findtext("FilterMatchName") or ""

    @property
    def properties(self) -> NamedList[ComponentParam]:
        """The component's parameters, indexable by name. Read-only."""
        return NamedList(self._properties, keys=("display_name",))

    def __iter__(self) -> Iterator[ComponentParam]:
        return iter(self._properties)

    def __len__(self) -> int:
        return len(self._properties)

    def __getitem__(self, key: int | str) -> ComponentParam:
        return self.properties[key]

    def __contains__(self, item: object) -> bool:
        return item in self.properties

    @property
    def sub_components(self) -> NamedList[Component]:
        """Components nested inside this one. Read-only.

        Masks applied to an effect are stored this way - each is itself a
        component (match name `AE.ADBE AEMask2`) whose parameters carry the
        feather, opacity, expansion and shape. ExtendScript exposes no
        equivalent, so this is XML-only.
        """
        return NamedList(self._sub_components, keys=("display_name", "match_name"))

    def add_mask(self) -> Component:
        """Attach a default mask to this effect and return it.

        Synthesizes the `AEMask2` sub-component exactly as 26_effect_mask
        stores it: the 27 default parameters, wired as a `SubComponents`
        entry beside the effect's `MatchName`. Masks number themselves by
        position (`01`, `02`, ...), and from the second one on the effect
        carries a `NextComponentNumber` allocation counter (76_two_masks).
        Adjust the geometry through the returned component's parameters
        (`Position`, `Anchor Point`, `Feather`, ...); use `path` on the
        Path parameter for drawn shapes.
        """
        if self._element.find("MatchName") is None:
            raise ValueError("component has no MatchName to anchor the mask")
        document = self.track_item.track.sequence.project._document
        subs = self._element.find("SubComponents")
        count = 0 if subs is None else len(subs.findall("SubComponent"))
        param_ids = build_mask_params(document)
        mask_id, mask_element = build_mask_component(
            document, param_ids, clip_role=False, instance_name=f"{count + 1:02d}"
        )
        attach_sub_mask(self._element, mask_id)
        if count:
            _stamp_next_component_number(self._inner(), count + 1)
        mask = _wrap_mask(document, mask_element, self.track_item, param_ids)
        self._sub_components.append(mask)
        return mask

    def _inner(self) -> ET.Element | None:
        inner = self._element.find("Component")
        if inner is None:
            # Audio components nest one level deeper.
            inner = self._element.find("AudioComponent/Component")
        return inner

    def __repr__(self) -> str:
        return (
            f"Component(display_name={self.display_name!r}, "
            f"{len(self._properties)} param(s))"
        )