Caption¶

class CaptionTrack:
    """A caption track on a sequence.

    Premiere keeps captions on their own kind of track - a data track, the
    third track group every sequence carries next to its video and audio
    ones. ExtendScript can create these (`Sequence.createCaptionTrack`) but
    never exposed their contents.
    """

    def __init__(self, _element: ET.Element, sequence: Sequence) -> None:
        self._element = _element
        self.sequence = sequence
        self._captions: list[Caption] = []

    @property
    def id(self) -> int:
        """The track's stored ID. Read-only."""
        return int(self._element.findtext("DataClipTrack/ClipTrack/Track/ID") or 0)

    @property
    def index(self) -> int:
        """The track's index within the sequence's caption tracks. Read-only."""
        return int(self._element.findtext("DataClipTrack/ClipTrack/Track/Index") or 0)

    @property
    def captions(self) -> list[Caption]:
        """The captions on this track, in timeline order. Read-only."""
        return self._captions

    @property
    def format(self) -> CaptionFormat:
        """The track's broadcast caption format. Read/write.

        The file stores ExtendScript's `CAPTION_FORMAT_*` constant split in
        two: `Format` holds its low word and `SubFormat` the high one (the
        three Teletext variants), and `SUBTITLE` elides both - so an
        absent `Format` reads as `SUBTITLE`. Swept straight off Premiere's
        own `createCaptionTrack` for all seven formats.
        """
        low = int(self._element.findtext("Format") or 0)
        high = int(self._element.findtext("SubFormat") or 0)
        return CaptionFormat((high << 16) | low)

    @format.setter
    def format(self, value: CaptionFormat) -> None:
        _validate_caption_format(value)
        write_track_format(self._element, int(value))

    def __repr__(self) -> str:
        return f"CaptionTrack(index={self.index}, captions={len(self._captions)})"

class Caption:
    """One caption on a caption track.

    Premiere stores a caption twice: as a track item carrying its
    frame-aligned placement on the timeline, and inside the imported caption
    stream carrying the source times it was authored with. `start` and `end`
    are the timeline ones; `source_start` and `source_end` are the stream's.
    """

    def __init__(self, _element: ET.Element, _text: str, track: CaptionTrack) -> None:
        self._element = _element
        self._text = _text
        self.track = track
        self._source_start = Time(0)
        self._source_end = Time(0)

    @property
    def text(self) -> str:
        """The caption text. Read/write.

        Setting it splices the new string into the styled-text payload,
        preserving the styling around it, and gives this caption's block
        its own payload copy under a fresh hash - what Premiere's own edit
        does. Empty text is refused: the format identifies its text as the
        payload's last string, so an empty one cannot be read back.
        """
        return self._text

    @text.setter
    def text(self, value: str) -> None:
        _validate_caption_text(value)
        self._write_payload(replace_payload_text(self._payload(), value))
        self._text = value

    @property
    def start(self) -> Time:
        """The start on the sequence timeline. Read-only."""
        return Time(int(self._element.findtext(_TRACK_ITEM + "Start") or 0))

    @property
    def end(self) -> Time:
        """The end on the sequence timeline. Read-only."""
        return Time(int(self._element.findtext(_TRACK_ITEM + "End") or 0))

    @property
    def source_start(self) -> Time:
        """The start as the imported caption stream states it. Read-only.

        Unlike `start`, this is not rounded to a frame boundary.
        """
        return self._source_start

    @property
    def source_end(self) -> Time:
        """The end as the imported caption stream states it. Read-only."""
        return self._source_end

    def _text_data(self) -> ET.Element | None:
        # The timeline block's FormattedTextData, through
        # BlockVector -> Block.
        document = self.track.sequence.project._document
        reference = self._element.find("BlockVector/BlockVectorItem")
        if reference is None:
            return None
        return document.resolve(reference).find("FormattedTextData")

    @property
    def font_size(self) -> float:
        """The caption's font size, as the captions panel shows it.
        Read/write.

        Stored inside the styled-text payload: every as-imported caption
        carries a per-run override (48.0), and a caption styled to the
        block-level base value (100.0) stores no override at all - decoded
        against 29_captions, 64_caption_style and
        80_subtitle_font_size_75, with the panel values confirmed by hand.

        Setting a size gives this caption's timeline block its own payload
        copy under a fresh hash, exactly as Premiere's own edit does; the
        imported stream's copy keeps its style, and Premiere refreshes the
        hash on open.
        """
        return read_font_size(self._payload())

    @font_size.setter
    def font_size(self, value: float) -> None:
        validate_positive_number(value)
        payload = self._payload()
        new_payload = write_font_size(payload, float(value))
        if new_payload != payload:
            self._write_payload(new_payload)

    def _style_float(self, slot: int) -> float | None:
        return read_style_float(self._payload(), slot)

    def _set_style_float(
        self, slot: int, value: float, enable: int | None = None
    ) -> None:
        validate_number(value)
        payload = write_style_float(self._payload(), slot, float(value))
        if enable is not None:
            payload = _write_table_flag(payload, _style_table, enable)
        self._write_payload(payload)

    def _style_color(self, slot: int) -> Color | None:
        return read_style_color(self._payload(), slot)

    def _set_style_color(
        self, slot: int, value: Color, enable: int | None = None
    ) -> None:
        validate_color(value)
        payload = write_style_color(self._payload(), slot, value)
        if enable is not None:
            payload = _write_table_flag(payload, _style_table, enable)
        self._write_payload(payload)

    def _block_float(self, slot: int) -> float | None:
        return read_block_float(self._payload(), slot)

    def _set_block_float(
        self, slot: int, value: float, enable: int | None = None
    ) -> None:
        validate_number(value)
        payload = write_block_float(self._payload(), slot, float(value))
        if enable is not None:
            payload = _write_table_flag(payload, _document_table, enable)
        self._write_payload(payload)

    def _block_color(self, slot: int) -> Color | None:
        return read_block_color(self._payload(), slot)

    def _set_block_color(
        self, slot: int, value: Color, enable: int | None = None
    ) -> None:
        validate_color(value)
        payload = write_block_color(self._payload(), slot, value)
        if enable is not None:
            payload = _write_table_flag(payload, _document_table, enable)
        self._write_payload(payload)

    @property
    def fill_color(self) -> Color | None:
        """The text's fill colour. Read/write.

        Named from 82_caption_style_sweep, where the panel's fill was set
        to the sentinel `RGB(11, 22, 33)`. Reads `None` when the caption
        has never been styled and stores no colour at all - Premiere then
        renders its format's default; setting one adds the field.
        """
        return self._style_color(_STYLE_FILL_SLOT)

    @fill_color.setter
    def fill_color(self, value: Color) -> None:
        self._set_style_color(_STYLE_FILL_SLOT, value)

    @property
    def stroke_color(self) -> Color | None:
        """The text's stroke (edge) colour. Read/write.

        Setting any stroke property also raises the group's enable flag
        (the Appearance panel's Stroke checkbox) - stored stroke values
        do not render without it.
        """
        return self._style_color(_STYLE_STROKE_COLOR_SLOT)

    @stroke_color.setter
    def stroke_color(self, value: Color) -> None:
        self._set_style_color(
            _STYLE_STROKE_COLOR_SLOT, value, enable=_STYLE_STROKE_ENABLED_SLOT
        )

    @property
    def stroke_width(self) -> float | None:
        """The stroke width. Read/write."""
        return self._style_float(_STYLE_STROKE_WIDTH_SLOT)

    @stroke_width.setter
    def stroke_width(self, value: float) -> None:
        self._set_style_float(
            _STYLE_STROKE_WIDTH_SLOT, value, enable=_STYLE_STROKE_ENABLED_SLOT
        )

    @property
    def tracking(self) -> float | None:
        """The letter tracking. Read/write."""
        return self._style_float(_STYLE_TRACKING_SLOT)

    @tracking.setter
    def tracking(self, value: float) -> None:
        self._set_style_float(_STYLE_TRACKING_SLOT, value)

    @property
    def leading(self) -> float | None:
        """The line leading. Read/write.

        Block-level, unlike the run-level fill and stroke: it applies to
        the whole caption.
        """
        return self._block_float(_BLOCK_LEADING_SLOT)

    @leading.setter
    def leading(self, value: float) -> None:
        self._set_block_float(_BLOCK_LEADING_SLOT, value)

    @property
    def shadow_color(self) -> Color | None:
        """The shadow's colour. Read/write."""
        return self._block_color(_BLOCK_SHADOW_COLOR_SLOT)

    @shadow_color.setter
    def shadow_color(self, value: Color) -> None:
        self._set_block_color(_BLOCK_SHADOW_COLOR_SLOT, value)

    @property
    def shadow_opacity(self) -> float | None:
        """The shadow's opacity. Read/write."""
        return self._block_float(_BLOCK_SHADOW_OPACITY_SLOT)

    @shadow_opacity.setter
    def shadow_opacity(self, value: float) -> None:
        self._set_block_float(_BLOCK_SHADOW_OPACITY_SLOT, value)

    @property
    def shadow_angle(self) -> float | None:
        """The shadow's angle in degrees. Read/write."""
        return self._block_float(_BLOCK_SHADOW_ANGLE_SLOT)

    @shadow_angle.setter
    def shadow_angle(self, value: float) -> None:
        self._set_block_float(_BLOCK_SHADOW_ANGLE_SLOT, value)

    @property
    def shadow_distance(self) -> float | None:
        """The shadow's distance. Read/write."""
        return self._block_float(_BLOCK_SHADOW_DISTANCE_SLOT)

    @shadow_distance.setter
    def shadow_distance(self, value: float) -> None:
        self._set_block_float(_BLOCK_SHADOW_DISTANCE_SLOT, value)

    @property
    def shadow_size(self) -> float | None:
        """The shadow's size. Read/write."""
        return self._block_float(_BLOCK_SHADOW_SIZE_SLOT)

    @shadow_size.setter
    def shadow_size(self, value: float) -> None:
        self._set_block_float(_BLOCK_SHADOW_SIZE_SLOT, value)

    @property
    def shadow_blur(self) -> float | None:
        """The shadow's blur. Read/write."""
        return self._block_float(_BLOCK_SHADOW_BLUR_SLOT)

    @shadow_blur.setter
    def shadow_blur(self, value: float) -> None:
        self._set_block_float(_BLOCK_SHADOW_BLUR_SLOT, value)

    @property
    def background_color(self) -> Color | None:
        """The caption background's colour. Read/write.

        Setting any background property also raises the group's enable
        flag (the Appearance panel's Background checkbox) - stored
        background values do not render without it.
        """
        return self._block_color(_BLOCK_BACKGROUND_COLOR_SLOT)

    @background_color.setter
    def background_color(self, value: Color) -> None:
        self._set_block_color(
            _BLOCK_BACKGROUND_COLOR_SLOT, value, enable=_BLOCK_BACKGROUND_ENABLED_SLOT
        )

    @property
    def background_opacity(self) -> float | None:
        """The background's opacity. Read/write."""
        return self._block_float(_BLOCK_BACKGROUND_OPACITY_SLOT)

    @background_opacity.setter
    def background_opacity(self, value: float) -> None:
        self._set_block_float(
            _BLOCK_BACKGROUND_OPACITY_SLOT, value, enable=_BLOCK_BACKGROUND_ENABLED_SLOT
        )

    @property
    def background_size(self) -> float | None:
        """The background's size (its padding). Read/write."""
        return self._block_float(_BLOCK_BACKGROUND_SIZE_SLOT)

    @background_size.setter
    def background_size(self, value: float) -> None:
        self._set_block_float(
            _BLOCK_BACKGROUND_SIZE_SLOT, value, enable=_BLOCK_BACKGROUND_ENABLED_SLOT
        )

    @property
    def background_corner_radius(self) -> float | None:
        """The background's corner radius. Read/write."""
        return self._block_float(_BLOCK_BACKGROUND_CORNER_SLOT)

    @background_corner_radius.setter
    def background_corner_radius(self, value: float) -> None:
        self._set_block_float(
            _BLOCK_BACKGROUND_CORNER_SLOT, value, enable=_BLOCK_BACKGROUND_ENABLED_SLOT
        )

    @property
    def font_family(self) -> str:
        """The font family the caption is set in. Read/write.

        Stored as a string in the payload's font vector. Premiere resolves
        an unknown family to a fallback on open, so setting one it does
        not have will not stick.
        """
        return read_font_family(self._payload())

    @font_family.setter
    def font_family(self, value: str) -> None:
        _validate_caption_text(value)
        self._write_payload(write_font_family(self._payload(), value))

    def _payload(self) -> bytes:
        document = self.track.sequence.project._document
        data = self._text_data()
        payload = None if data is None else document.payload(data)
        if payload is None:
            raise ValueError("caption has no styled-text payload")
        return payload

    def _write_payload(self, payload: bytes) -> None:
        document = self.track.sequence.project._document
        data = self._text_data()
        if data is None:
            raise ValueError("caption has no styled-text payload")
        write_payload_element(document, data, payload)

    def __repr__(self) -> str:
        return f"Caption(text={self._text!r}, start={self.start.seconds:.3f}s)"