Text & Transcription

Classes for handling transcriptions and rendering text overlays on video.

Transcription Classes

Transcription

Transcription

Source code in src/videopython/base/transcription.py

class Transcription:
    def __init__(
        self,
        segments: list[TranscriptionSegment] | None = None,
        words: list[TranscriptionWord] | None = None,
        language: str | None = None,
    ):
        """Initialize Transcription from either segments or words.

        Args:
            segments: Pre-constructed segments (backward compatible)
            words: Words to group into segments by speaker (for diarization)
            language: ISO 639-1 language code detected during transcription (e.g. "en", "pl")

        Raises:
            ValueError: If both or neither arguments are provided
        """
        if (segments is None) == (words is None):
            raise ValueError("Exactly one of 'segments' or 'words' must be provided")

        self.language = language

        if segments is not None:
            self.segments = segments
            self.speakers = {s.speaker for s in segments if s.speaker is not None}
        else:
            assert words is not None
            self.segments = self._words_to_segments(words)
            self.speakers = {w.speaker for w in words if w.speaker is not None}

    @property
    def words(self) -> list[TranscriptionWord]:
        """Return all words from all segments."""
        all_words = []
        for segment in self.segments:
            all_words.extend(segment.words)
        return all_words

    def _words_to_segments(self, words: list[TranscriptionWord]) -> list[TranscriptionSegment]:
        """Group words into segments based on speaker changes."""
        if not words:
            return []

        current_speaker = words[0].speaker
        current_words: list[TranscriptionWord] = []
        segments = []

        for word in words:
            if current_speaker == word.speaker:
                current_words.append(word)
            else:
                segments.append(TranscriptionSegment.from_words(current_words, speaker=current_speaker))
                current_speaker = word.speaker
                current_words = [word]

        if current_words:
            segments.append(TranscriptionSegment.from_words(current_words, speaker=current_speaker))

        return segments

    def speaker_stats(self) -> dict[str, float]:
        """Calculate speaking time percentage for each speaker.

        Returns:
            Dictionary mapping speaker names to their percentage of total speaking time
        """
        all_words = []
        for segment in self.segments:
            all_words.extend(segment.words)

        speaking_stats: dict[str, float] = {speaker: 0.0 for speaker in self.speakers}
        total_speaking_time = 0.0

        for word in all_words:
            if word.speaker is not None:
                speak_time = word.end - word.start
                total_speaking_time += speak_time
                speaking_stats[word.speaker] += speak_time

        if total_speaking_time > 0:
            for speaker in speaking_stats:
                speaking_stats[speaker] /= total_speaking_time

        return speaking_stats

    def offset(self, time: float) -> Transcription:
        """Return a new Transcription with all timings offset by the provided time value."""
        offset_segments = []

        for segment in self.segments:
            offset_words = [
                TranscriptionWord(start=w.start + time, end=w.end + time, word=w.word, speaker=w.speaker)
                for w in segment.words
            ]
            # ``replace`` carries text, speaker, and confidence fields through a
            # pure timing shift unchanged -- only timestamps move.
            offset_segments.append(
                replace(segment, start=segment.start + time, end=segment.end + time, words=offset_words)
            )

        return Transcription(segments=offset_segments, language=self.language)

    def standardize_segments(self, *, time: float | None = None, num_words: int | None = None) -> Transcription:
        """Return a new Transcription with standardized segments.

        Segments are also split on speaker changes so that each segment contains
        words from a single speaker.

        Args:
            time: Maximum duration in seconds for each segment
            num_words: Maximum number of words per segment

        Raises:
            ValueError: If both time and num_words are provided or if neither is provided
        """
        if (time is None) == (num_words is None):
            raise ValueError("Exactly one of 'time' or 'num_words' must be provided")

        if time is not None and time <= 0:
            raise ValueError("Time must be positive")

        if num_words is not None and num_words <= 0:
            raise ValueError("Number of words must be positive")

        # Collect all words from all segments
        all_words: list[TranscriptionWord] = []
        for segment in self.segments:
            all_words.extend(segment.words)

        if not all_words:
            return Transcription(segments=[], language=self.language)

        standardized_segments: list[TranscriptionSegment] = []

        def _flush(words: list[TranscriptionWord]) -> None:
            if not words:
                return
            # Words here are regrouped across original segments, so the source
            # segments' confidence fields no longer apply -- left as None.
            standardized_segments.append(TranscriptionSegment.from_words(words, speaker=words[0].speaker))

        if time is not None:
            current_words: list[TranscriptionWord] = []

            for word in all_words:
                if not current_words:
                    current_words = [word]
                elif word.speaker != current_words[0].speaker or word.end - current_words[0].start > time:
                    _flush(current_words)
                    current_words = [word]
                else:
                    current_words.append(word)

            _flush(current_words)

        elif num_words is not None:
            current_words = []

            for word in all_words:
                if not current_words:
                    current_words = [word]
                elif word.speaker != current_words[0].speaker or len(current_words) >= num_words:
                    _flush(current_words)
                    current_words = [word]
                else:
                    current_words.append(word)

            _flush(current_words)

        return Transcription(segments=standardized_segments, language=self.language)

    def capitalize_sentences(self) -> Transcription:
        """Return a new Transcription with sentence-start capitalization.

        The first letter of the first spoken word and of every word that
        follows sentence-ending punctuation (``.``, ``!``, ``?``, ``…``) is
        upper-cased. Remaining characters are left untouched, so acronyms and
        proper nouns from the source transcription are preserved. Timing,
        speaker, and language are carried through unchanged.

        Abbreviation detection is intentionally not attempted: a token like
        ``"U.S."`` is treated as a sentence end. This heuristic is adequate
        for burned-in subtitles and avoids a brittle abbreviation list.
        """
        capitalized_segments: list[TranscriptionSegment] = []
        start_of_sentence = True

        for segment in self.segments:
            new_words: list[TranscriptionWord] = []
            for word in segment.words:
                token = word.word
                if start_of_sentence:
                    idx = next((i for i, ch in enumerate(token) if ch.isalpha()), None)
                    if idx is not None:
                        token = token[:idx] + token[idx].upper() + token[idx + 1 :]
                        start_of_sentence = False
                if token.rstrip(_TRAILING_WRAPPERS).endswith(_SENTENCE_TERMINATORS):
                    start_of_sentence = True
                new_words.append(TranscriptionWord(start=word.start, end=word.end, word=token, speaker=word.speaker))

            # Casing-only rewrite: segment boundaries, speaker, and confidence
            # are unchanged; only the tokens (and joined text) differ.
            capitalized_segments.append(replace(segment, text=" ".join(w.word for w in new_words), words=new_words))

        return Transcription(segments=capitalized_segments, language=self.language)

    def chunk_segments(self, max_words: int) -> Transcription:
        """Return a new Transcription splitting each segment into smaller cues.

        Each segment is split into consecutive groups of at most ``max_words``
        words, using that group's own first/last word timings. Unlike
        :meth:`standardize_segments`, words are never merged across the
        original segments, so silence gaps between segments are preserved and
        subtitles do not linger over pauses. Speaker, confidence, and language
        metadata are carried through unchanged.

        Args:
            max_words: Maximum number of words per output segment.

        Raises:
            ValueError: If ``max_words`` is not positive.
        """
        if max_words <= 0:
            raise ValueError("max_words must be positive")

        chunked_segments: list[TranscriptionSegment] = []
        for segment in self.segments:
            words = segment.words
            if not words:
                # Nothing to split; emit a fresh copy so the result never
                # aliases the source segment.
                chunked_segments.append(replace(segment, words=list(segment.words)))
                continue
            for i in range(0, len(words), max_words):
                group = words[i : i + max_words]
                # Splitting *within* one source segment -- its confidence
                # fields still apply, so carry them through.
                chunked_segments.append(
                    TranscriptionSegment.from_words(
                        group,
                        speaker=segment.speaker,
                        avg_logprob=segment.avg_logprob,
                        no_speech_prob=segment.no_speech_prob,
                        compression_ratio=segment.compression_ratio,
                    )
                )

        return Transcription(segments=chunked_segments, language=self.language)

    def slice(self, start: float, end: float) -> Transcription | None:
        """Return a new Transcription containing only words within the time range.

        Slices at word-level granularity: words that overlap with the time range
        are included, and new segments are reconstructed from the included words.

        Args:
            start: Start time in seconds (inclusive)
            end: End time in seconds (exclusive)

        Returns:
            New Transcription with words/segments in the time range, or None if no words overlap
        """
        if start >= end:
            return None

        # Collect all words that overlap with the time range
        overlapping_words: list[TranscriptionWord] = []
        for segment in self.segments:
            for word in segment.words:
                # Include word if it overlaps with our time range
                if word.end > start and word.start < end:
                    overlapping_words.append(word)

        if not overlapping_words:
            return None

        # Reconstruct segments from the overlapping words
        # Group consecutive words by speaker to form segments
        sliced_segments: list[TranscriptionSegment] = []
        current_speaker = overlapping_words[0].speaker
        current_words: list[TranscriptionWord] = []

        for word in overlapping_words:
            if word.speaker == current_speaker:
                current_words.append(word)
            else:
                # Finish current segment (speaker is ambiguous across the
                # original segments these words came from -- confidence omitted)
                if current_words:
                    sliced_segments.append(TranscriptionSegment.from_words(current_words, speaker=current_speaker))
                # Start new segment
                current_speaker = word.speaker
                current_words = [word]

        # Add final segment
        if current_words:
            sliced_segments.append(TranscriptionSegment.from_words(current_words, speaker=current_speaker))

        return Transcription(segments=sliced_segments, language=self.language)

    @staticmethod
    def _format_srt_time(seconds: float) -> str:
        """Format seconds as SRT timestamp (HH:MM:SS,mmm)."""
        hours = int(seconds // 3600)
        minutes = int((seconds % 3600) // 60)
        secs = int(seconds % 60)
        millis = int(round((seconds - int(seconds)) * 1000))
        return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"

    @staticmethod
    def _parse_srt_time(timestamp: str) -> float:
        """Parse SRT timestamp (HH:MM:SS,mmm) to seconds."""
        hours, minutes, rest = timestamp.strip().split(":")
        seconds, millis = rest.split(",")
        return int(hours) * 3600 + int(minutes) * 60 + int(seconds) + int(millis) / 1000

    def to_srt(self) -> str:
        """Export transcription as an SRT subtitle string."""
        blocks = []
        for i, segment in enumerate(self.segments, start=1):
            start = self._format_srt_time(segment.start)
            end = self._format_srt_time(segment.end)
            blocks.append(f"{i}\n{start} --> {end}\n{segment.text}")
        return "\n\n".join(blocks) + "\n" if blocks else ""

    @classmethod
    def from_srt(cls, srt: str) -> Transcription:
        """Parse an SRT string into a Transcription.

        Each SRT block becomes a segment with a single word spanning the full
        segment duration (word-level timing is not available in SRT).

        Args:
            srt: SRT-formatted string.

        Returns:
            Transcription with one segment per SRT block.
        """
        segments: list[TranscriptionSegment] = []
        blocks = [b.strip() for b in srt.strip().split("\n\n") if b.strip()]

        for block in blocks:
            lines = block.split("\n")
            # SRT block: index, timestamp line, one or more text lines
            if len(lines) < 3:
                continue
            timestamp_line = lines[1]
            start_str, end_str = timestamp_line.split("-->")
            start = cls._parse_srt_time(start_str)
            end = cls._parse_srt_time(end_str)
            text = "\n".join(lines[2:]).strip()

            words = [TranscriptionWord(start=start, end=end, word=text)]
            segments.append(TranscriptionSegment(start=start, end=end, text=text, words=words))

        return cls(segments=segments)

    def save_srt(self, path: str | Path) -> None:
        """Write transcription to an SRT file.

        Args:
            path: Output file path.
        """
        Path(path).write_text(self.to_srt(), encoding="utf-8")

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary for JSON serialization."""
        return {
            "segments": [s.to_dict() for s in self.segments],
            "language": self.language,
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> Transcription:
        """Create Transcription from dictionary."""
        return cls(
            segments=[TranscriptionSegment.from_dict(s) for s in data["segments"]],
            language=data.get("language"),
        )

words property

words: list[TranscriptionWord]

Return all words from all segments.

__init__

__init__(
    segments: list[TranscriptionSegment] | None = None,
    words: list[TranscriptionWord] | None = None,
    language: str | None = None,
)

Initialize Transcription from either segments or words.

Parameters:

Name	Type	Description	Default
segments	list[TranscriptionSegment] | None	Pre-constructed segments (backward compatible)	None
words	list[TranscriptionWord] | None	Words to group into segments by speaker (for diarization)	None
language	str | None	ISO 639-1 language code detected during transcription (e.g. "en", "pl")	None

Raises:

Type	Description
ValueError	If both or neither arguments are provided

Source code in src/videopython/base/transcription.py

def __init__(
    self,
    segments: list[TranscriptionSegment] | None = None,
    words: list[TranscriptionWord] | None = None,
    language: str | None = None,
):
    """Initialize Transcription from either segments or words.

    Args:
        segments: Pre-constructed segments (backward compatible)
        words: Words to group into segments by speaker (for diarization)
        language: ISO 639-1 language code detected during transcription (e.g. "en", "pl")

    Raises:
        ValueError: If both or neither arguments are provided
    """
    if (segments is None) == (words is None):
        raise ValueError("Exactly one of 'segments' or 'words' must be provided")

    self.language = language

    if segments is not None:
        self.segments = segments
        self.speakers = {s.speaker for s in segments if s.speaker is not None}
    else:
        assert words is not None
        self.segments = self._words_to_segments(words)
        self.speakers = {w.speaker for w in words if w.speaker is not None}

speaker_stats

speaker_stats() -> dict[str, float]

Calculate speaking time percentage for each speaker.

Returns:

Type	Description
dict[str, float]	Dictionary mapping speaker names to their percentage of total speaking time

Source code in src/videopython/base/transcription.py

def speaker_stats(self) -> dict[str, float]:
    """Calculate speaking time percentage for each speaker.

    Returns:
        Dictionary mapping speaker names to their percentage of total speaking time
    """
    all_words = []
    for segment in self.segments:
        all_words.extend(segment.words)

    speaking_stats: dict[str, float] = {speaker: 0.0 for speaker in self.speakers}
    total_speaking_time = 0.0

    for word in all_words:
        if word.speaker is not None:
            speak_time = word.end - word.start
            total_speaking_time += speak_time
            speaking_stats[word.speaker] += speak_time

    if total_speaking_time > 0:
        for speaker in speaking_stats:
            speaking_stats[speaker] /= total_speaking_time

    return speaking_stats

offset

offset(time: float) -> Transcription

Return a new Transcription with all timings offset by the provided time value.

Source code in src/videopython/base/transcription.py

def offset(self, time: float) -> Transcription:
    """Return a new Transcription with all timings offset by the provided time value."""
    offset_segments = []

    for segment in self.segments:
        offset_words = [
            TranscriptionWord(start=w.start + time, end=w.end + time, word=w.word, speaker=w.speaker)
            for w in segment.words
        ]
        # ``replace`` carries text, speaker, and confidence fields through a
        # pure timing shift unchanged -- only timestamps move.
        offset_segments.append(
            replace(segment, start=segment.start + time, end=segment.end + time, words=offset_words)
        )

    return Transcription(segments=offset_segments, language=self.language)

standardize_segments

standardize_segments(
    *,
    time: float | None = None,
    num_words: int | None = None,
) -> Transcription

Return a new Transcription with standardized segments.

Segments are also split on speaker changes so that each segment contains words from a single speaker.

Parameters:

Name	Type	Description	Default
time	float | None	Maximum duration in seconds for each segment	None
num_words	int | None	Maximum number of words per segment	None

Raises:

Type	Description
ValueError	If both time and num_words are provided or if neither is provided

Source code in src/videopython/base/transcription.py

def standardize_segments(self, *, time: float | None = None, num_words: int | None = None) -> Transcription:
    """Return a new Transcription with standardized segments.

    Segments are also split on speaker changes so that each segment contains
    words from a single speaker.

    Args:
        time: Maximum duration in seconds for each segment
        num_words: Maximum number of words per segment

    Raises:
        ValueError: If both time and num_words are provided or if neither is provided
    """
    if (time is None) == (num_words is None):
        raise ValueError("Exactly one of 'time' or 'num_words' must be provided")

    if time is not None and time <= 0:
        raise ValueError("Time must be positive")

    if num_words is not None and num_words <= 0:
        raise ValueError("Number of words must be positive")

    # Collect all words from all segments
    all_words: list[TranscriptionWord] = []
    for segment in self.segments:
        all_words.extend(segment.words)

    if not all_words:
        return Transcription(segments=[], language=self.language)

    standardized_segments: list[TranscriptionSegment] = []

    def _flush(words: list[TranscriptionWord]) -> None:
        if not words:
            return
        # Words here are regrouped across original segments, so the source
        # segments' confidence fields no longer apply -- left as None.
        standardized_segments.append(TranscriptionSegment.from_words(words, speaker=words[0].speaker))

    if time is not None:
        current_words: list[TranscriptionWord] = []

        for word in all_words:
            if not current_words:
                current_words = [word]
            elif word.speaker != current_words[0].speaker or word.end - current_words[0].start > time:
                _flush(current_words)
                current_words = [word]
            else:
                current_words.append(word)

        _flush(current_words)

    elif num_words is not None:
        current_words = []

        for word in all_words:
            if not current_words:
                current_words = [word]
            elif word.speaker != current_words[0].speaker or len(current_words) >= num_words:
                _flush(current_words)
                current_words = [word]
            else:
                current_words.append(word)

        _flush(current_words)

    return Transcription(segments=standardized_segments, language=self.language)

capitalize_sentences

capitalize_sentences() -> Transcription

Return a new Transcription with sentence-start capitalization.

The first letter of the first spoken word and of every word that follows sentence-ending punctuation (., !, ?, …) is upper-cased. Remaining characters are left untouched, so acronyms and proper nouns from the source transcription are preserved. Timing, speaker, and language are carried through unchanged.

Abbreviation detection is intentionally not attempted: a token like "U.S." is treated as a sentence end. This heuristic is adequate for burned-in subtitles and avoids a brittle abbreviation list.

Source code in src/videopython/base/transcription.py

def capitalize_sentences(self) -> Transcription:
    """Return a new Transcription with sentence-start capitalization.

    The first letter of the first spoken word and of every word that
    follows sentence-ending punctuation (``.``, ``!``, ``?``, ``…``) is
    upper-cased. Remaining characters are left untouched, so acronyms and
    proper nouns from the source transcription are preserved. Timing,
    speaker, and language are carried through unchanged.

    Abbreviation detection is intentionally not attempted: a token like
    ``"U.S."`` is treated as a sentence end. This heuristic is adequate
    for burned-in subtitles and avoids a brittle abbreviation list.
    """
    capitalized_segments: list[TranscriptionSegment] = []
    start_of_sentence = True

    for segment in self.segments:
        new_words: list[TranscriptionWord] = []
        for word in segment.words:
            token = word.word
            if start_of_sentence:
                idx = next((i for i, ch in enumerate(token) if ch.isalpha()), None)
                if idx is not None:
                    token = token[:idx] + token[idx].upper() + token[idx + 1 :]
                    start_of_sentence = False
            if token.rstrip(_TRAILING_WRAPPERS).endswith(_SENTENCE_TERMINATORS):
                start_of_sentence = True
            new_words.append(TranscriptionWord(start=word.start, end=word.end, word=token, speaker=word.speaker))

        # Casing-only rewrite: segment boundaries, speaker, and confidence
        # are unchanged; only the tokens (and joined text) differ.
        capitalized_segments.append(replace(segment, text=" ".join(w.word for w in new_words), words=new_words))

    return Transcription(segments=capitalized_segments, language=self.language)

chunk_segments

chunk_segments(max_words: int) -> Transcription

Return a new Transcription splitting each segment into smaller cues.

Each segment is split into consecutive groups of at most max_words words, using that group's own first/last word timings. Unlike :meth:standardize_segments, words are never merged across the original segments, so silence gaps between segments are preserved and subtitles do not linger over pauses. Speaker, confidence, and language metadata are carried through unchanged.

Parameters:

Name	Type	Description	Default
max_words	int	Maximum number of words per output segment.	required

Raises:

Type	Description
ValueError	If max_words is not positive.

Source code in src/videopython/base/transcription.py

def chunk_segments(self, max_words: int) -> Transcription:
    """Return a new Transcription splitting each segment into smaller cues.

    Each segment is split into consecutive groups of at most ``max_words``
    words, using that group's own first/last word timings. Unlike
    :meth:`standardize_segments`, words are never merged across the
    original segments, so silence gaps between segments are preserved and
    subtitles do not linger over pauses. Speaker, confidence, and language
    metadata are carried through unchanged.

    Args:
        max_words: Maximum number of words per output segment.

    Raises:
        ValueError: If ``max_words`` is not positive.
    """
    if max_words <= 0:
        raise ValueError("max_words must be positive")

    chunked_segments: list[TranscriptionSegment] = []
    for segment in self.segments:
        words = segment.words
        if not words:
            # Nothing to split; emit a fresh copy so the result never
            # aliases the source segment.
            chunked_segments.append(replace(segment, words=list(segment.words)))
            continue
        for i in range(0, len(words), max_words):
            group = words[i : i + max_words]
            # Splitting *within* one source segment -- its confidence
            # fields still apply, so carry them through.
            chunked_segments.append(
                TranscriptionSegment.from_words(
                    group,
                    speaker=segment.speaker,
                    avg_logprob=segment.avg_logprob,
                    no_speech_prob=segment.no_speech_prob,
                    compression_ratio=segment.compression_ratio,
                )
            )

    return Transcription(segments=chunked_segments, language=self.language)

slice

slice(start: float, end: float) -> Transcription | None

Return a new Transcription containing only words within the time range.

Slices at word-level granularity: words that overlap with the time range are included, and new segments are reconstructed from the included words.

Parameters:

Name	Type	Description	Default
start	float	Start time in seconds (inclusive)	required
end	float	End time in seconds (exclusive)	required

Returns:

Type	Description
Transcription | None	New Transcription with words/segments in the time range, or None if no words overlap

Source code in src/videopython/base/transcription.py

def slice(self, start: float, end: float) -> Transcription | None:
    """Return a new Transcription containing only words within the time range.

    Slices at word-level granularity: words that overlap with the time range
    are included, and new segments are reconstructed from the included words.

    Args:
        start: Start time in seconds (inclusive)
        end: End time in seconds (exclusive)

    Returns:
        New Transcription with words/segments in the time range, or None if no words overlap
    """
    if start >= end:
        return None

    # Collect all words that overlap with the time range
    overlapping_words: list[TranscriptionWord] = []
    for segment in self.segments:
        for word in segment.words:
            # Include word if it overlaps with our time range
            if word.end > start and word.start < end:
                overlapping_words.append(word)

    if not overlapping_words:
        return None

    # Reconstruct segments from the overlapping words
    # Group consecutive words by speaker to form segments
    sliced_segments: list[TranscriptionSegment] = []
    current_speaker = overlapping_words[0].speaker
    current_words: list[TranscriptionWord] = []

    for word in overlapping_words:
        if word.speaker == current_speaker:
            current_words.append(word)
        else:
            # Finish current segment (speaker is ambiguous across the
            # original segments these words came from -- confidence omitted)
            if current_words:
                sliced_segments.append(TranscriptionSegment.from_words(current_words, speaker=current_speaker))
            # Start new segment
            current_speaker = word.speaker
            current_words = [word]

    # Add final segment
    if current_words:
        sliced_segments.append(TranscriptionSegment.from_words(current_words, speaker=current_speaker))

    return Transcription(segments=sliced_segments, language=self.language)

to_srt

to_srt() -> str

Export transcription as an SRT subtitle string.

Source code in src/videopython/base/transcription.py

def to_srt(self) -> str:
    """Export transcription as an SRT subtitle string."""
    blocks = []
    for i, segment in enumerate(self.segments, start=1):
        start = self._format_srt_time(segment.start)
        end = self._format_srt_time(segment.end)
        blocks.append(f"{i}\n{start} --> {end}\n{segment.text}")
    return "\n\n".join(blocks) + "\n" if blocks else ""

from_srt classmethod

from_srt(srt: str) -> Transcription

Parse an SRT string into a Transcription.

Each SRT block becomes a segment with a single word spanning the full segment duration (word-level timing is not available in SRT).

Parameters:

Name	Type	Description	Default
srt	str	SRT-formatted string.	required

Returns:

Type	Description
Transcription	Transcription with one segment per SRT block.

Source code in src/videopython/base/transcription.py

@classmethod
def from_srt(cls, srt: str) -> Transcription:
    """Parse an SRT string into a Transcription.

    Each SRT block becomes a segment with a single word spanning the full
    segment duration (word-level timing is not available in SRT).

    Args:
        srt: SRT-formatted string.

    Returns:
        Transcription with one segment per SRT block.
    """
    segments: list[TranscriptionSegment] = []
    blocks = [b.strip() for b in srt.strip().split("\n\n") if b.strip()]

    for block in blocks:
        lines = block.split("\n")
        # SRT block: index, timestamp line, one or more text lines
        if len(lines) < 3:
            continue
        timestamp_line = lines[1]
        start_str, end_str = timestamp_line.split("-->")
        start = cls._parse_srt_time(start_str)
        end = cls._parse_srt_time(end_str)
        text = "\n".join(lines[2:]).strip()

        words = [TranscriptionWord(start=start, end=end, word=text)]
        segments.append(TranscriptionSegment(start=start, end=end, text=text, words=words))

    return cls(segments=segments)

save_srt

save_srt(path: str | Path) -> None

Write transcription to an SRT file.

Parameters:

Name	Type	Description	Default
path	str | Path	Output file path.	required

Source code in src/videopython/base/transcription.py

def save_srt(self, path: str | Path) -> None:
    """Write transcription to an SRT file.

    Args:
        path: Output file path.
    """
    Path(path).write_text(self.to_srt(), encoding="utf-8")

to_dict

to_dict() -> dict[str, Any]

Convert to dictionary for JSON serialization.

Source code in src/videopython/base/transcription.py

def to_dict(self) -> dict[str, Any]:
    """Convert to dictionary for JSON serialization."""
    return {
        "segments": [s.to_dict() for s in self.segments],
        "language": self.language,
    }

from_dict classmethod

from_dict(data: dict[str, Any]) -> Transcription

Create Transcription from dictionary.

Source code in src/videopython/base/transcription.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> Transcription:
    """Create Transcription from dictionary."""
    return cls(
        segments=[TranscriptionSegment.from_dict(s) for s in data["segments"]],
        language=data.get("language"),
    )

TranscriptionSegment

TranscriptionSegment dataclass

Source code in src/videopython/base/transcription.py

@dataclass
class TranscriptionSegment:
    start: float
    end: float
    text: str
    words: list[TranscriptionWord]
    speaker: str | None = None
    avg_logprob: float | None = None
    no_speech_prob: float | None = None
    compression_ratio: float | None = None

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary for JSON serialization."""
        return {
            "start": self.start,
            "end": self.end,
            "text": self.text,
            "words": [w.to_dict() for w in self.words],
            "speaker": self.speaker,
            "avg_logprob": self.avg_logprob,
            "no_speech_prob": self.no_speech_prob,
            "compression_ratio": self.compression_ratio,
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> TranscriptionSegment:
        """Create TranscriptionSegment from dictionary."""
        return cls(
            start=data["start"],
            end=data["end"],
            text=data["text"],
            words=[TranscriptionWord.from_dict(w) for w in data["words"]],
            speaker=data.get("speaker"),
            avg_logprob=data.get("avg_logprob"),
            no_speech_prob=data.get("no_speech_prob"),
            compression_ratio=data.get("compression_ratio"),
        )

    @classmethod
    def from_words(
        cls,
        words: list[TranscriptionWord],
        *,
        speaker: str | None = None,
        avg_logprob: float | None = None,
        no_speech_prob: float | None = None,
        compression_ratio: float | None = None,
    ) -> TranscriptionSegment:
        """Build a segment spanning ``words``, deriving start/end/text from them.

        ``words`` must be non-empty: ``start``/``end`` come from the first/last
        word and ``text`` is the words joined by single spaces. Speaker and the
        confidence fields are passed through so callers re-segmenting *within* a
        known source segment can preserve them; callers regrouping words across
        segments (where these are ambiguous) simply omit them, leaving ``None``.
        The ``words`` list is copied, so the result never aliases the caller's.
        """
        if not words:
            raise ValueError("from_words requires a non-empty word list")
        return cls(
            start=words[0].start,
            end=words[-1].end,
            text=" ".join(w.word for w in words),
            words=list(words),
            speaker=speaker,
            avg_logprob=avg_logprob,
            no_speech_prob=no_speech_prob,
            compression_ratio=compression_ratio,
        )

to_dict

to_dict() -> dict[str, Any]

Convert to dictionary for JSON serialization.

Source code in src/videopython/base/transcription.py

def to_dict(self) -> dict[str, Any]:
    """Convert to dictionary for JSON serialization."""
    return {
        "start": self.start,
        "end": self.end,
        "text": self.text,
        "words": [w.to_dict() for w in self.words],
        "speaker": self.speaker,
        "avg_logprob": self.avg_logprob,
        "no_speech_prob": self.no_speech_prob,
        "compression_ratio": self.compression_ratio,
    }

from_dict classmethod

from_dict(data: dict[str, Any]) -> TranscriptionSegment

Create TranscriptionSegment from dictionary.

Source code in src/videopython/base/transcription.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> TranscriptionSegment:
    """Create TranscriptionSegment from dictionary."""
    return cls(
        start=data["start"],
        end=data["end"],
        text=data["text"],
        words=[TranscriptionWord.from_dict(w) for w in data["words"]],
        speaker=data.get("speaker"),
        avg_logprob=data.get("avg_logprob"),
        no_speech_prob=data.get("no_speech_prob"),
        compression_ratio=data.get("compression_ratio"),
    )

from_words classmethod

from_words(
    words: list[TranscriptionWord],
    *,
    speaker: str | None = None,
    avg_logprob: float | None = None,
    no_speech_prob: float | None = None,
    compression_ratio: float | None = None,
) -> TranscriptionSegment

Build a segment spanning words, deriving start/end/text from them.

words must be non-empty: start/end come from the first/last word and text is the words joined by single spaces. Speaker and the confidence fields are passed through so callers re-segmenting within a known source segment can preserve them; callers regrouping words across segments (where these are ambiguous) simply omit them, leaving None. The words list is copied, so the result never aliases the caller's.

Source code in src/videopython/base/transcription.py

@classmethod
def from_words(
    cls,
    words: list[TranscriptionWord],
    *,
    speaker: str | None = None,
    avg_logprob: float | None = None,
    no_speech_prob: float | None = None,
    compression_ratio: float | None = None,
) -> TranscriptionSegment:
    """Build a segment spanning ``words``, deriving start/end/text from them.

    ``words`` must be non-empty: ``start``/``end`` come from the first/last
    word and ``text`` is the words joined by single spaces. Speaker and the
    confidence fields are passed through so callers re-segmenting *within* a
    known source segment can preserve them; callers regrouping words across
    segments (where these are ambiguous) simply omit them, leaving ``None``.
    The ``words`` list is copied, so the result never aliases the caller's.
    """
    if not words:
        raise ValueError("from_words requires a non-empty word list")
    return cls(
        start=words[0].start,
        end=words[-1].end,
        text=" ".join(w.word for w in words),
        words=list(words),
        speaker=speaker,
        avg_logprob=avg_logprob,
        no_speech_prob=no_speech_prob,
        compression_ratio=compression_ratio,
    )

TranscriptionWord

TranscriptionWord dataclass

Source code in src/videopython/base/transcription.py

@dataclass
class TranscriptionWord:
    start: float
    end: float
    word: str
    speaker: str | None = None

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary for JSON serialization."""
        return {
            "start": self.start,
            "end": self.end,
            "word": self.word,
            "speaker": self.speaker,
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> TranscriptionWord:
        """Create TranscriptionWord from dictionary."""
        return cls(
            start=data["start"],
            end=data["end"],
            word=data["word"],
            speaker=data.get("speaker"),
        )

to_dict

to_dict() -> dict[str, Any]

Convert to dictionary for JSON serialization.

Source code in src/videopython/base/transcription.py

def to_dict(self) -> dict[str, Any]:
    """Convert to dictionary for JSON serialization."""
    return {
        "start": self.start,
        "end": self.end,
        "word": self.word,
        "speaker": self.speaker,
    }

from_dict classmethod

from_dict(data: dict[str, Any]) -> TranscriptionWord

Create TranscriptionWord from dictionary.

Source code in src/videopython/base/transcription.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> TranscriptionWord:
    """Create TranscriptionWord from dictionary."""
    return cls(
        start=data["start"],
        end=data["end"],
        word=data["word"],
        speaker=data.get("speaker"),
    )

Overlay Classes

TranscriptionOverlay

Render transcriptions as subtitles with word-level highlighting:

from videopython.base import Video
from videopython.editing import TranscriptionOverlay

video = Video.from_path("input.mp4")
# transcription = ... (from AudioToText or manually created)

overlay = TranscriptionOverlay(
    style="boxed",       # boxed | outline | clean | karaoke
    region="bottom",     # top | center | bottom
    font_scale=0.055,    # font height as a fraction of frame height
    # font_filename is optional; omit it (or pass None) to use the
    # bundled default font. Pass a path to use your own .ttf/.otf.
    font_filename=None,
)
video = overlay.apply(video, transcription)

Geometry is resolution-independent by default: font_scale/region are fractions of the frame, so the same overlay renders correctly at any output size and an upstream face_crop/resize cannot make it overflow. The absolute fields (font_size, position, box_width, explicit colors, ...) remain optional advanced overrides for back-compat -- leave them unset to derive from the style/region/font_scale presets. Because the layout is frame-relative and shared between the dry-run and the render, VideoEdit.validate() rejects an un-fittable subtitle plan up front instead of crashing mid-render.

TranscriptionOverlay

Bases: Effect

Renders animated word-by-word subtitles with the current word highlighted.

Each word lights up in the highlight color as it is spoken, based on transcription timestamps. Requires a word-level transcription, which the runner supplies via the requires=("transcription",) declaration.

Geometry is resolution-relative by default (font_scale/region), so a plan validated by VideoEdit.validate() that passes will also render; a plan that cannot fit fails fast in :meth:predict_metadata instead of crashing mid-render after expensive upstream ops.

Source code in src/videopython/editing/transcription_overlay.py

class TranscriptionOverlay(Effect):
    """Renders animated word-by-word subtitles with the current word highlighted.

    Each word lights up in the highlight color as it is spoken, based on
    transcription timestamps. Requires a word-level transcription, which the
    runner supplies via the ``requires=("transcription",)`` declaration.

    Geometry is resolution-relative by default (``font_scale``/``region``), so
    a plan validated by ``VideoEdit.validate()`` that passes will also render;
    a plan that cannot fit fails fast in :meth:`predict_metadata` instead of
    crashing mid-render after expensive upstream ops.
    """

    op: Literal["add_subtitles"] = "add_subtitles"
    streamable: ClassVar[bool] = False
    requires: ClassVar[tuple[str, ...]] = ("transcription",)

    # ---- primary, resolution-independent surface ----
    style: SubtitleStyle = Field(
        SubtitleStyle.BOXED,
        description='Look preset bundling colors/border/background/highlight: "boxed", "outline", "clean", "karaoke".',
    )
    region: SubtitleRegion = Field(
        SubtitleRegion.BOTTOM,
        description='Vertical placement band: "top", "center", or "bottom" of the frame.',
    )
    font_scale: float = Field(
        0.055,
        gt=0.0,
        le=0.5,
        description=(
            "Base font height as a fraction of frame height (resolution-independent; the recommended "
            "way to size subtitles). Auto-shrinks toward `min_font_scale` if a cue would overflow."
        ),
    )
    min_font_scale: float = Field(
        0.030,
        gt=0.0,
        le=0.5,
        description=(
            "Lower bound for auto-fit shrinking, as a fraction of frame height. A cue that cannot fit "
            "even at this size is a validation error rather than an illegible render."
        ),
    )
    max_words_per_cue: int | None = Field(
        5,
        ge=1,
        description=(
            "Maximum words shown on screen at once. Each transcription segment is re-chunked into "
            "cues of at most this many words, without bridging the silence gaps between segments, so "
            "subtitles stay readable and don't linger over pauses. None preserves the source "
            "transcription's segmentation."
        ),
    )
    capitalize: bool = Field(
        True,
        description=(
            "Capitalize the first letter of each sentence (first word, and words after '.', '!', '?'). "
            "Fixes lowercase sentence starts from word-level speech-to-text. Set False to render text "
            "exactly as transcribed."
        ),
    )
    font_filename: str | None = Field(
        None,
        description="Path to a .ttf font file for rendering subtitle text, or None for the bundled default font.",
    )
    highlight_bold_font: str | None = Field(
        None, description="Path to a bold .ttf font for the highlighted word, or None to use the regular font."
    )

    # ---- advanced overrides: None => derive from style/region/font_scale ----
    font_size: int | None = Field(
        None,
        ge=1,
        description=(
            "Advanced override: absolute base font size in pixels. Leave None to derive from "
            "`font_scale` (recommended -- resolution-independent and overflow-safe)."
        ),
    )
    font_border_size: int | None = Field(
        None, ge=0, description="Advanced override for outline thickness in px. None takes it from `style`."
    )
    text_color: RGBColor | None = Field(
        None, description="Advanced override for default text color [R, G, B] (0-255). None takes it from `style`."
    )
    background_color: RGBAColor | None | Literal["auto"] = Field(
        _AUTO,
        description=(
            'Advanced override for the box background [R, G, B, A] (0-255). "auto" takes it from `style`; '
            "null explicitly disables the background."
        ),
    )
    background_padding: int | None = Field(
        None, ge=0, description="Advanced override: px between text and background edge. None takes it from `style`."
    )
    highlight_color: RGBColor | None = Field(
        None, description="Advanced override for the spoken-word color [R, G, B]. None takes it from `style`."
    )
    highlight_size_multiplier: float | None = Field(
        None, gt=0, description="Advanced override: scale factor for the highlighted word. None takes it from `style`."
    )
    position: tuple[float, float] | None = Field(
        None,
        description="Advanced override: box center as normalized (x, y). None derives it from `region`.",
    )
    box_width: float | None = Field(
        None,
        gt=0.0,
        le=1.0,
        description="Advanced override: box width as a fraction of frame width in (0, 1]. None uses 0.6.",
    )
    text_align: TextAlign | None = Field(
        None, description='Advanced override: text alignment within the box. None uses "center".'
    )
    anchor: AnchorPoint | None = Field(
        None, description="Advanced override: which point of the box sits at the position. None uses center."
    )
    margin: int | tuple[int, int, int, int] | None = Field(
        None,
        description="Advanced override: space around the box in px (or [top, right, bottom, left]). None uses 20.",
    )

    # ------------------------------------------------------------- resolution

    def _style_params(self) -> _StyleParams:
        """Effective look: the ``style`` preset overlaid by any explicit overrides."""
        p = _STYLE_PRESETS[self.style]
        bg = p.background_color if self.background_color == _AUTO else self.background_color
        return _StyleParams(
            text_color=self.text_color or p.text_color,
            highlight_color=self.highlight_color or p.highlight_color,
            border=self.font_border_size if self.font_border_size is not None else p.border,
            background_color=bg,
            background_padding=(
                self.background_padding if self.background_padding is not None else p.background_padding
            ),
            highlight_size_multiplier=(
                self.highlight_size_multiplier
                if self.highlight_size_multiplier is not None
                else p.highlight_size_multiplier
            ),
        )

    def _resolve_config(self) -> _ResolvedConfig:
        """Resolve every override-or-preset field to a concrete value once."""
        return _ResolvedConfig(
            position=self.position if self.position is not None else _REGION_POSITION[self.region],
            anchor=self.anchor if self.anchor is not None else AnchorPoint.CENTER,
            box_width=self.box_width if self.box_width is not None else 0.6,
            text_align=self.text_align if self.text_align is not None else TextAlign.CENTER,
            margin=self.margin if self.margin is not None else 20,
            style=self._style_params(),
        )

    def _transform(self, transcription: Transcription) -> Transcription:
        """Apply the cue transforms render and dry-run MUST share."""
        if self.max_words_per_cue is not None:
            transcription = transcription.chunk_segments(self.max_words_per_cue)
        if self.capitalize:
            transcription = transcription.capitalize_sentences()
        return transcription

    def _place_cue(self, img_text: ImageText, text: str, font_px: int, cfg: _ResolvedConfig) -> _CueBox | None:
        """Measure ``text`` at ``font_px`` and clamp its box inside the margins.

        Returns ``None`` for a degenerate (whitespace-only) cue. ``fits`` is
        False when the box is larger than the drawable area even after
        clamping -- i.e. shrinking the font is the only remedy. Used by both
        the fit search and the renderer, so they never diverge. Margin math
        comes from ``ImageText.available_region`` (one source of truth with
        ``measure_text_box``).

        The highlight multiplier is threaded in so the measurement is
        worst-case for the animated word enlargement: a cue that fits at base
        size but overflows once a word is highlighted is rejected here (and
        auto-shrunk by ``_resolve_layout``) instead of crashing mid-render.
        """
        rect = img_text.measure_text_box(
            text=text,
            font_filename=self.font_filename,
            xy=cfg.position,
            box_width=cfg.box_width,
            font_size=font_px,
            anchor=cfg.anchor,
            margin=cfg.margin,
            highlight_size_multiplier=cfg.style.highlight_size_multiplier,
            highlight_bold_font=self.highlight_bold_font,
        )
        if rect.height == 0:
            return None
        box_w = int(rect.width)
        box_h = rect.height
        left, top, avail_w, avail_h = img_text.available_region(cfg.margin)
        # The box must fit the drawable area, AND the worst-case rendered line
        # (incl. the enlarged highlighted word, or an unbreakable long word)
        # must fit the box -- else the centered line spills off-frame at draw
        # time. Failing this shrinks the font in ``_resolve_layout``.
        fits = box_w <= avail_w and box_h <= avail_h and rect.content_width <= box_w
        x = min(max(int(round(rect.x)), left), left + avail_w - box_w)
        y = min(max(int(round(rect.y)), top), top + avail_h - box_h)
        return _CueBox(x=x, y=y, box_w=box_w, height=box_h, fits=fits)

    def _resolve_layout(self, width: int, height: int, transcription: Transcription) -> _SubtitleLayout:
        """Single source of truth for config + font size + fit (render & dry-run)."""
        segments = self._transform(transcription).segments
        cues = [s for s in segments if s.text.strip()]
        cfg = self._resolve_config()

        desired = self.font_size if self.font_size is not None else max(1, round(self.font_scale * height))
        floor = max(1, round(self.min_font_scale * height))
        # Never search above the desired size nor below the legible floor --
        # but if the user pinned a font_size below the floor, honor it.
        lo = min(desired, floor)

        img_text = ImageText(image_size=(height, width), background=(0, 0, 0, 0))

        def first_unfit(font_px: int) -> TranscriptionSegment | None:
            for cue in cues:
                box = self._place_cue(img_text, cue.text, font_px, cfg)
                if box is not None and not box.fits:
                    return cue
            return None

        # "fits" is monotonic in font size (a larger font never fits where a
        # smaller one didn't -- box width is font-independent and box height
        # is non-decreasing in font size), so binary-search the largest fit.
        if first_unfit(desired) is None:
            return _SubtitleLayout(segments, cfg, desired, True, None)
        offender = first_unfit(lo)
        if offender is not None:
            error = (
                f"Subtitle cue {offender.text!r} cannot fit in a {width}x{height} frame even at the "
                f"minimum font size ({lo}px, min_font_scale={self.min_font_scale}). Lower min_font_scale, "
                f"reduce max_words_per_cue, widen box_width, or render at a larger resolution."
            )
            return _SubtitleLayout(segments, cfg, lo, False, error)
        low, high = lo, desired  # invariant: fits at low, not at high
        while high - low > 1:
            mid = (low + high) // 2
            if first_unfit(mid) is None:
                low = mid
            else:
                high = mid
        return _SubtitleLayout(segments, cfg, low, True, None)

    # ------------------------------------------------------------- timeline

    def _get_active_segment(self, transcription: Transcription, timestamp: float) -> TranscriptionSegment | None:
        for segment in transcription.segments:
            if segment.start <= timestamp <= segment.end:
                return segment
        return None

    def _get_active_word_index(self, segment: TranscriptionSegment, timestamp: float) -> int | None:
        for i, word in enumerate(segment.words):
            if word.start <= timestamp <= word.end:
                return i
        return None

    def _create_text_overlay(
        self,
        video_shape: tuple[int, int, int],
        segment: TranscriptionSegment,
        highlight_word_index: int | None,
        layout: _SubtitleLayout,
        cache: dict[tuple[str, int | None], np.ndarray],
    ) -> np.ndarray:
        height, width = video_shape[:2]
        cache_key = (segment.text, highlight_word_index)
        if cache_key in cache:
            return cache[cache_key]

        cfg = layout.config
        img_text = ImageText(image_size=(height, width), background=(0, 0, 0, 0))
        box = self._place_cue(img_text, segment.text, layout.font_px, cfg)
        if box is not None:
            sp = cfg.style
            # Absolute, pre-clamped placement (anchor=TOP_LEFT, explicit px box,
            # margin already applied) -- the same numbers _resolve_layout used,
            # so a layout that validated cannot raise OutOfBoundsError here.
            img_text.write_text_box(
                text=segment.text,
                font_filename=self.font_filename,
                xy=(box.x, box.y),
                box_width=box.box_w,
                font_size=layout.font_px,
                font_border_size=sp.border,
                text_color=sp.text_color,
                background_color=sp.background_color,
                background_padding=sp.background_padding,
                place=cfg.text_align,
                anchor=AnchorPoint.TOP_LEFT,
                margin=0,
                words=[w.word for w in segment.words],
                highlight_word_index=highlight_word_index,
                highlight_color=sp.highlight_color,
                highlight_size_multiplier=sp.highlight_size_multiplier,
                highlight_bold_font=self.highlight_bold_font,
            )

        overlay_image = img_text.img_array
        cache[cache_key] = overlay_image
        return overlay_image

    def apply(  # type: ignore[override]
        self,
        video: Video,
        transcription: Transcription | None = None,
    ) -> Video:
        if transcription is None:
            raise ValueError(
                "TranscriptionOverlay requires transcription data. "
                "Pass it via VideoEdit.run(context={'transcription': ...}) or directly to apply()."
            )

        height, width = video.frame_shape[:2]
        layout = self._resolve_layout(width, height, transcription)
        if not layout.fits:
            # Should be unreachable when the plan went through validate(); kept
            # as defense in depth so a direct apply() still fails clearly
            # rather than crashing mid-render in ImageText.
            raise ValueError(layout.error)

        # Per-call memo of rendered overlays, keyed by (cue text, highlighted
        # word). Local rather than instance state so the model stays stateless
        # and re-entrant -- a reused instance can render differently sized
        # videos without serving a stale-resolution overlay.
        cache: dict[tuple[str, int | None], np.ndarray] = {}
        transformed = Transcription(segments=layout.segments, language=transcription.language)

        logger.info("Applying transcription overlay (font %dpx)...", layout.font_px)
        new_frames = []
        for frame_index, frame in enumerate(tqdm(video.frames, desc="Transcription overlay")):
            timestamp = frame_index / video.fps
            active_segment = self._get_active_segment(transformed, timestamp)
            if active_segment is None:
                new_frames.append(frame)
                continue
            highlight_word_index = self._get_active_word_index(active_segment, timestamp)
            text_overlay = self._create_text_overlay(
                video.frame_shape, active_segment, highlight_word_index, layout, cache
            )
            new_frames.append(self._apply_overlay_to_frame(frame, text_overlay))

        new_video = Video.from_frames(np.array(new_frames), fps=video.fps)
        new_video.audio = video.audio
        return new_video

    def predict_metadata(
        self,
        meta: VideoMetadata,
        transcription: Transcription | None = None,
        **_context: Any,
    ) -> VideoMetadata:
        """Identity for metadata (shape/count preserved) -- but fail fast here
        if the resolved subtitles cannot fit the predicted frame.

        This is the backstop that closes the validate/run gap: ``VideoEdit``
        runs it during the dry-run, so an un-fittable plan is rejected before
        any frame/GPU work, symmetric with the timing/dimension checks. Mirrors
        ``SilenceRemoval``: with no ``transcription`` in the validate context
        the layout cannot be checked, so this is a no-op identity (the same
        conditional guarantee as time re-basing).
        """
        if transcription is None:
            return meta
        layout = self._resolve_layout(meta.width, meta.height, transcription)
        if not layout.fits:
            raise ValueError(layout.error)
        return meta

    def _apply_overlay_to_frame(self, frame: np.ndarray, overlay: np.ndarray) -> np.ndarray:
        frame_pil = Image.fromarray(frame)
        overlay_pil = Image.fromarray(overlay)
        frame_pil.paste(overlay_pil, (0, 0), overlay_pil)
        return np.array(frame_pil)

predict_metadata

predict_metadata(
    meta: VideoMetadata,
    transcription: Transcription | None = None,
    **_context: Any,
) -> VideoMetadata

Identity for metadata (shape/count preserved) -- but fail fast here if the resolved subtitles cannot fit the predicted frame.

This is the backstop that closes the validate/run gap: VideoEdit runs it during the dry-run, so an un-fittable plan is rejected before any frame/GPU work, symmetric with the timing/dimension checks. Mirrors SilenceRemoval: with no transcription in the validate context the layout cannot be checked, so this is a no-op identity (the same conditional guarantee as time re-basing).

Source code in src/videopython/editing/transcription_overlay.py

def predict_metadata(
    self,
    meta: VideoMetadata,
    transcription: Transcription | None = None,
    **_context: Any,
) -> VideoMetadata:
    """Identity for metadata (shape/count preserved) -- but fail fast here
    if the resolved subtitles cannot fit the predicted frame.

    This is the backstop that closes the validate/run gap: ``VideoEdit``
    runs it during the dry-run, so an un-fittable plan is rejected before
    any frame/GPU work, symmetric with the timing/dimension checks. Mirrors
    ``SilenceRemoval``: with no ``transcription`` in the validate context
    the layout cannot be checked, so this is a no-op identity (the same
    conditional guarantee as time re-basing).
    """
    if transcription is None:
        return meta
    layout = self._resolve_layout(meta.width, meta.height, transcription)
    if not layout.fits:
        raise ValueError(layout.error)
    return meta

ImageText

Low-level text rendering on images:

ImageText

Source code in src/videopython/base/image_text.py

class ImageText:
    def __init__(
        self,
        image_size: tuple[int, int] = (1920, 1080),  # (height, width) - NumPy convention
        mode: str = "RGBA",
        background: RGBAColor = (0, 0, 0, 0),  # Transparent background
    ):
        """
        Initialize an image for text rendering.

        Args:
            image_size: Dimensions of the image (height, width) - NumPy convention
            mode: Image mode (RGB, RGBA, etc.)
            background: Background color with alpha channel

        Raises:
            ValueError: If image_size dimensions are not positive
        """
        if image_size[0] <= 0 or image_size[1] <= 0:
            raise ValueError("Image dimensions must be positive")

        if len(background) != 4:
            raise ValueError("Background color must be RGBA (4 values)")

        self.image_size = image_size  # Stored as (height, width)
        # PIL uses (width, height), so we reverse for Image.new
        self.image = Image.new(mode, (image_size[1], image_size[0]), color=background)
        self._draw = ImageDraw.Draw(self.image)
        self._font_cache: dict[tuple[str | None, int], ImageFont.FreeTypeFont | ImageFont.ImageFont] = {}

    @property
    def img_array(self) -> np.ndarray:
        """Convert the PIL Image to a numpy array."""
        return np.array(self.image)

    def save(self, filename: str) -> None:
        """Save the image to a file."""
        if not filename:
            raise ValueError("Filename cannot be empty")
        self.image.save(filename)

    def _fit_font_width(self, text: str, font: str | None, max_width: int) -> int:
        """
        Find the maximum font size where the text width is less than or equal to max_width.

        Args:
            text: The text to measure
            font: Path to the font file
            max_width: Maximum allowed width in pixels

        Returns:
            The maximum font size that fits within max_width

        Raises:
            ValueError: If text is empty or max_width is too small for any font size
        """
        if not text:
            return 1  # Default to minimum size for empty text

        if max_width <= 0:
            raise ValueError("Maximum width must be positive")

        font_size = 1
        text_width = self.get_text_dimensions(font, font_size, text)[0]
        while text_width < max_width:
            font_size += 1
            text_width = self.get_text_dimensions(font, font_size, text)[0]
        max_font_size = font_size - 1
        if max_font_size < 1:
            raise ValueError(f"Max width {max_width} is too small for any font size!")
        return max_font_size

    def _fit_font_height(self, text: str, font: str | None, max_height: int) -> int:
        """
        Find the maximum font size where the text height is less than or equal to max_height.

        Args:
            text: The text to measure
            font: Path to the font file
            max_height: Maximum allowed height in pixels

        Returns:
            The maximum font size that fits within max_height

        Raises:
            ValueError: If text is empty or max_height is too small for any font size
        """
        if not text:
            return 1  # Default to minimum size for empty text

        if max_height <= 0:
            raise ValueError("Maximum height must be positive")

        font_size = 1
        text_height = self.get_text_dimensions(font, font_size, text)[1]
        while text_height < max_height:
            font_size += 1
            text_height = self.get_text_dimensions(font, font_size, text)[1]
        max_font_size = font_size - 1
        if max_font_size < 1:
            raise ValueError(f"Max height {max_height} is too small for any font size!")
        return max_font_size

    def _get_font_size(
        self,
        text: str,
        font: str | None,
        max_width: int | None = None,
        max_height: int | None = None,
    ) -> int:
        """
        Get maximum font size for text to fit within given dimensions.

        Args:
            text: The text to fit
            font: Path to the font file
            max_width: Maximum allowed width in pixels
            max_height: Maximum allowed height in pixels

        Returns:
            The maximum font size that fits within constraints

        Raises:
            ValueError: If neither max_width nor max_height is provided, or text is empty
        """
        if not text:
            raise ValueError("Text cannot be empty")

        if max_width is None and max_height is None:
            raise ValueError("You need to pass max_width or max_height")

        if max_width is not None and max_width <= 0:
            raise ValueError("Maximum width must be positive")

        if max_height is not None and max_height <= 0:
            raise ValueError("Maximum height must be positive")

        width_font_size = self._fit_font_width(text, font, max_width) if max_width is not None else None
        height_font_size = self._fit_font_height(text, font, max_height) if max_height is not None else None

        sizes = [size for size in [width_font_size, height_font_size] if size is not None]
        if not sizes:
            raise ValueError("No valid font size could be calculated")

        return min(sizes)

    def _process_margin(self, margin: MarginType) -> tuple[int, int, int, int]:
        """
        Process the margin parameter into individual top, right, bottom, left values.

        Args:
            margin: A single int for all sides, or a tuple of 4 values for each side

        Returns:
            Tuple of (top, right, bottom, left) margin values

        Raises:
            ValueError: If margin tuple doesn't have exactly 4 values
        """
        if isinstance(margin, int):
            if margin < 0:
                raise ValueError("Margin cannot be negative")
            return margin, margin, margin, margin
        elif isinstance(margin, tuple) and len(margin) == 4:
            if any(m < 0 for m in margin):
                raise ValueError("Margin values cannot be negative")
            return margin
        else:
            raise ValueError("Margin must be an int or a tuple of 4 ints")

    def _convert_position(
        self, position: PositionType, margin_top: int, margin_left: int, available_width: int, available_height: int
    ) -> tuple[float, float]:
        """
        Convert a position from relative (0-1) to absolute pixels.

        Args:
            position: Position as (x, y) coordinates, either as pixels or relative (0-1)
            margin_top: Top margin in pixels
            margin_left: Left margin in pixels
            available_width: Available width considering margins
            available_height: Available height considering margins

        Returns:
            Position in absolute pixel coordinates (might still be float)
        """
        x_pos, y_pos = position

        # Convert relative position (0-1) to absolute pixels
        if isinstance(x_pos, float) and 0 <= x_pos <= 1:
            x_pos = margin_left + x_pos * available_width
        if isinstance(y_pos, float) and 0 <= y_pos <= 1:
            y_pos = margin_top + y_pos * available_height

        return x_pos, y_pos

    def _calculate_position(
        self,
        text_size: tuple[int, int],
        position: PositionType,
        anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
        margin: MarginType = 0,
    ) -> tuple[int, int]:
        """
        Calculate the absolute position based on anchor point, relative positioning and margins.

        Args:
            text_size: Width and height of the text in pixels
            position: Either absolute coordinates (int) or relative to frame size (float 0-1)
            anchor: Which part of the text to anchor at the position
            margin: Margin in pixels (single value or [top, right, bottom, left])

        Returns:
            Absolute x, y coordinates for text placement

        Raises:
            ValueError: If position or margin values are invalid
        """
        if not isinstance(text_size, tuple) or len(text_size) != 2:
            raise ValueError("text_size must be a tuple of (width, height)")

        text_width, text_height = text_size

        # Process margins
        margin_top, margin_right, margin_bottom, margin_left = self._process_margin(margin)

        # Calculate available area considering margins
        available_width = self.image_size[1] - margin_left - margin_right
        available_height = self.image_size[0] - margin_top - margin_bottom

        # Convert relative position to absolute if needed
        x_pos, y_pos = self._convert_position(position, margin_top, margin_left, available_width, available_height)

        # Apply margin to absolute position when using 0,0 as starting point
        if x_pos == 0 and anchor in AnchorPoint.left_anchors():
            x_pos = margin_left
        if y_pos == 0 and anchor in AnchorPoint.top_anchors():
            y_pos = margin_top

        # Adjust position based on anchor point
        if anchor in AnchorPoint.center_anchors():
            x_pos -= text_width // 2
        elif anchor in AnchorPoint.right_anchors():
            x_pos -= text_width

        if anchor in AnchorPoint.middle_anchors():
            y_pos -= text_height // 2
        elif anchor in AnchorPoint.bottom_anchors():
            y_pos -= text_height

        return int(x_pos), int(y_pos)

    def write_text(
        self,
        text: str,
        font_filename: str | None,
        xy: PositionType,
        font_size: int | None = 11,
        font_border_size: int = 0,
        color: RGBColor = (0, 0, 0),
        max_width: int | None = None,
        max_height: int | None = None,
        anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
        margin: MarginType = 0,
    ) -> tuple[int, int]:
        """
        Write text to the image with advanced positioning options.

        Args:
            text: Text to be written
            font_filename: Path to the font file
            xy: Position (x,y) either as absolute pixels (int) or relative to frame (float 0-1)
            font_size: Size of the font in points, or None to auto-calculate
            font_border_size: Size of border around text in pixels (0 for no border)
            color: RGB color of the text
            max_width: Maximum width for auto font sizing
            max_height: Maximum height for auto font sizing
            anchor: Which part of the text to anchor at the position
            margin: Margin in pixels (single value or [top, right, bottom, left])

        Returns:
            Dimensions of the rendered text (width, height)

        Raises:
            ValueError: If text is empty or font parameters are invalid
            OutOfBoundsError: If the text would be rendered outside the image bounds
        """
        if not text:
            raise ValueError("Text cannot be empty")

        if font_size is not None and font_size <= 0:
            raise ValueError("Font size must be positive")

        if font_border_size < 0:
            raise ValueError("Font border size cannot be negative")

        if font_size is None and (max_width is None or max_height is None):
            raise ValueError("Must set either `font_size`, or both `max_width` and `max_height`!")
        elif font_size is None:
            font_size = self._get_font_size(text, font_filename, max_width, max_height)

        # Get or create the font object (with caching)
        font = self._get_font(font_filename, font_size)
        text_dimensions = self.get_text_dimensions(font_filename, font_size, text)

        # Calculate the position based on anchor point and margins
        x, y = self._calculate_position(text_dimensions, xy, anchor, margin)

        # Verify text will fit within bounds
        if x < 0 or y < 0 or x + text_dimensions[0] > self.image_size[1] or y + text_dimensions[1] > self.image_size[0]:
            raise OutOfBoundsError(f"Text with size {text_dimensions} at position ({x}, {y}) is out of bounds!")

        # Draw border if requested
        if font_border_size > 0:
            # Draw text border by drawing text in multiple positions around the main text
            for border_x in range(-font_border_size, font_border_size + 1):
                for border_y in range(-font_border_size, font_border_size + 1):
                    if border_x != 0 or border_y != 0:  # Skip the center position
                        self._draw.text((x + border_x, y + border_y), text, font=font, fill=(0, 0, 0))

        # Draw the main text on top
        self._draw.text((x, y), text, font=font, fill=color)
        return text_dimensions

    def _get_font(self, font_filename: str | None, font_size: int) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
        """
        Get a font object, using cache if available.

        Resolves via :func:`videopython.base.fonts.load_font`, so a missing,
        unreadable, or ``None`` ``font_filename`` gracefully falls back to
        the bundled default font instead of raising.

        Args:
            font_filename: Path to the font file, or None for the default.
            font_size: Size of the font in points

        Returns:
            Font object for rendering text
        """
        key = (font_filename, font_size)
        if key not in self._font_cache:
            self._font_cache[key] = load_font(font_filename, font_size)
        return self._font_cache[key]

    def get_text_dimensions(self, font_filename: str | None, font_size: int, text: str) -> tuple[int, int]:
        """
        Return dimensions (width, height) of the rendered text.

        Args:
            font_filename: Path to the font file
            font_size: Size of the font in points
            text: Text to measure

        Returns:
            Tuple of (width, height) for the rendered text

        Raises:
            ValueError: If font parameters are invalid or text is empty
        """
        if not text:
            return (0, 0)  # Empty text has no dimensions

        if font_size <= 0:
            raise ValueError("Font size must be positive")

        font = self._get_font(font_filename, font_size)
        try:
            bbox = font.getbbox(text)
            if bbox is None:
                return (0, 0)  # Handle case where getbbox returns None
            return bbox[2:] if len(bbox) >= 4 else (0, 0)
        except Exception as e:
            raise ValueError(f"Error measuring text: {str(e)}")

    def _get_font_baseline_offset(
        self,
        base_font_filename: str | None,
        base_font_size: int,
        highlight_font_filename: str | None,
        highlight_font_size: int,
    ) -> int:
        """
        Calculate the vertical offset needed to align baselines of different fonts and sizes.

        Args:
            base_font_filename: Path to the base font file
            base_font_size: Font size of normal text
            highlight_font_filename: Path to the highlight font file
            highlight_font_size: Font size of highlighted text

        Returns:
            Vertical offset in pixels to align highlighted text baseline with normal text baseline
        """
        base_font = self._get_font(base_font_filename, base_font_size)
        highlight_font = self._get_font(highlight_font_filename, highlight_font_size)

        # Use a reference character to get baseline metrics
        # We use 'A' as it's a good reference for ascender height
        ref_char = "A"

        # Get bounding boxes for the reference character
        base_bbox = base_font.getbbox(ref_char)
        highlight_bbox = highlight_font.getbbox(ref_char)

        if base_bbox is None or highlight_bbox is None:
            return 0  # Fallback if bbox calculation fails

        # The baseline offset is the difference in the top of the bounding box
        # since getbbox returns (left, top, right, bottom) where top is negative for ascenders
        base_ascent = -base_bbox[1]  # Distance from baseline to top of character
        highlight_ascent = -highlight_bbox[1]  # Distance from baseline to top of character

        # Calculate the offset needed to align baselines
        # If highlighted text has a larger ascent, we need to move it down
        baseline_offset = highlight_ascent - base_ascent

        return baseline_offset

    def _split_lines_by_width(
        self,
        text: str,
        font_filename: str | None,
        font_size: int,
        box_width: int,
    ) -> list[str]:
        """
        Split the text into lines that fit within the specified width.

        Args:
            text: Text to split into lines
            font_filename: Path to the font file
            font_size: Size of the font in points
            box_width: Maximum width for each line in pixels

        Returns:
            List of text lines that fit within box_width

        Raises:
            ValueError: If font parameters are invalid or box_width is too small
        """
        if not text:
            return []  # Empty text produces no lines

        if box_width <= 0:
            raise ValueError("Box width must be positive")

        if font_size <= 0:
            raise ValueError("Font size must be positive")

        words = text.split()
        if not words:
            return []  # No words means no lines

        # Handle single-word case efficiently
        if len(words) == 1:
            return [text]

        split_lines: list[list[str]] = []
        current_line: list[str] = []

        for word in words:
            # If current line is empty and this word is too long for box_width,
            # we'll have to split the word itself (not implemented)
            if not current_line and self.get_text_dimensions(font_filename, font_size, word)[0] > box_width:
                # Just add the word anyway, it'll overflow but we can't do better without splitting words
                split_lines.append([word])
                continue

            # Try adding the word to current line
            new_line = " ".join(current_line + [word]) if current_line else word
            size = self.get_text_dimensions(font_filename, font_size, new_line)
            if size[0] <= box_width:
                current_line.append(word)
            else:
                # This word doesn't fit, start new line
                if current_line:  # Only if we have a current line to add
                    split_lines.append(current_line)
                current_line = [word]

        # Add the last line if it has content
        if current_line:
            split_lines.append(current_line)

        # Join the words in each line with spaces
        lines = [" ".join(line) for line in split_lines]
        return lines

    def available_region(self, margin: MarginType = 0) -> tuple[int, int, int, int]:
        """The drawable area inside ``margin`` as ``(left, top, width, height)``.

        Single source of truth for margin-inset geometry: used by
        :meth:`measure_text_box` and by callers that need to clamp a box
        within the margins without re-deriving the margin math.
        """
        margin_top, margin_right, margin_bottom, margin_left = self._process_margin(margin)
        available_width = self.image_size[1] - margin_left - margin_right
        available_height = self.image_size[0] - margin_top - margin_bottom
        return margin_left, margin_top, available_width, available_height

    def measure_text_box(
        self,
        text: str,
        font_filename: str | None,
        xy: PositionType,
        box_width: int | float | None = None,
        font_size: int = 11,
        anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
        margin: MarginType = 0,
        highlight_size_multiplier: float = 1.0,
        highlight_bold_font: str | None = None,
    ) -> TextBoxRect:
        """Measure where a wrapped text box would land, without drawing it.

        Pure: resolves margins/box-width/position, wraps the text, applies the
        anchor, and bounds-checks against the image — the exact math
        :meth:`write_text_box` used to do inline.

        ``highlight_size_multiplier > 1`` makes the measurement worst-case for
        an *animated* highlight (any word may be the enlarged one over the
        cue's lifetime): wrapping reserves room so even an enlarged word keeps
        its line within ``box_width``, and ``height`` uses each line's tallest
        possible highlighted variant. With the default ``1.0`` the result is
        byte-identical to the plain base-font measurement, so existing callers
        and ``place`` (alignment) are unaffected.

        Returns:
            A :class:`TextBoxRect`. ``fits`` is ``False`` when the box would
            fall outside the image bounds (the condition that makes
            :meth:`write_text_box` raise :class:`OutOfBoundsError`).

        Raises:
            ValueError: If ``text`` is empty, ``font_size`` is not positive,
                or an absolute ``box_width`` is not positive.
        """
        if not text:
            raise ValueError("Text cannot be empty")

        if font_size <= 0:
            raise ValueError("Font size must be positive")

        # Process margins to determine available area (shared with callers
        # that clamp boxes inside the margins -- see ``available_region``).
        margin_left, margin_top, available_width, available_height = self.available_region(margin)

        # Handle relative box width
        if box_width is None:
            box_width = available_width
        elif isinstance(box_width, float) and 0 < box_width <= 1:
            box_width = int(available_width * box_width)
        elif isinstance(box_width, int) and box_width <= 0:
            raise ValueError("Box width must be positive")

        # Calculate initial position based on margin and anchor before splitting text
        x_pos, y_pos = self._convert_position(xy, margin_top, margin_left, available_width, available_height)

        # Wrap at the real box width (same as the renderer).
        lines = self._split_lines_by_width(text, font_filename, font_size, int(box_width))

        # Per-line extent. With an animated highlight any word may be the
        # enlarged one over the cue's lifetime, so each line contributes the
        # widest/tallest variant it could ever render as.
        # ``_highlighted_line_max_extent`` derives that envelope from the same
        # per-word geometry the renderer uses (single source of truth).
        hl_mult = max(1.0, highlight_size_multiplier)
        content_width = 0
        lines_height = 0
        for line in lines:
            if hl_mult > 1.0:
                line_w, line_h = self._highlighted_line_max_extent(
                    line, font_filename, font_size, hl_mult, highlight_bold_font
                )
            else:
                line_w, line_h = self.get_text_dimensions(font_filename, font_size, line)
            content_width = max(content_width, line_w)
            lines_height += line_h
        if lines_height == 0:
            # No renderable lines (e.g. whitespace-only text); position is the
            # unadjusted insertion point and the box trivially "fits".
            return TextBoxRect(
                x=x_pos, y=y_pos, width=box_width, height=0, fits=True, lines=tuple(lines), content_width=0
            )

        # Final position calculation based on anchor point
        if anchor in AnchorPoint.center_anchors():
            x_pos -= box_width // 2
        elif anchor in AnchorPoint.right_anchors():
            x_pos -= box_width

        if anchor in AnchorPoint.middle_anchors():
            y_pos -= lines_height // 2
        elif anchor in AnchorPoint.bottom_anchors():
            y_pos -= lines_height

        fits = not (
            x_pos < 0
            or y_pos < 0
            or x_pos + box_width > self.image_size[1]
            or y_pos + lines_height > self.image_size[0]
        )
        return TextBoxRect(
            x=x_pos,
            y=y_pos,
            width=box_width,
            height=lines_height,
            fits=fits,
            lines=tuple(lines),
            content_width=content_width,
        )

    def write_text_box(
        self,
        text: str,
        font_filename: str | None,
        xy: PositionType,
        box_width: int | float | None = None,
        font_size: int = 11,
        font_border_size: int = 0,
        text_color: RGBColor = (0, 0, 0),
        background_color: RGBAColor | None = None,
        background_padding: int = 0,
        place: TextAlign = TextAlign.LEFT,
        anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
        margin: MarginType = 0,
        words: list[str] | None = None,
        highlight_word_index: int | None = None,
        highlight_color: RGBColor | None = None,
        highlight_size_multiplier: float = DEFAULT_HIGHLIGHT_SIZE_MULTIPLIER,
        highlight_bold_font: str | None = None,
    ) -> tuple[int, int]:
        """
        Write text in a box with advanced positioning and alignment options.

        Args:
            text: Text to be written inside the box
            font_filename: Path to the font file
            xy: Position (x,y) either as absolute pixels (int) or relative to frame (float 0-1)
            box_width: Width of the box in pixels (int) or relative to frame width (float 0-1)
            font_size: Font size in points
            font_border_size: Size of border around text in pixels (0 for no border)
            text_color: RGB color of the text
            background_color: If set, adds background color to the text box. Expects RGBA values.
            background_padding: Number of padding pixels to add when adding text background color
            place: Text alignment within the box (TextAlign.LEFT, TextAlign.RIGHT, TextAlign.CENTER)
            anchor: Which part of the text box to anchor at the position
            margin: Margin in pixels (single value or [top, right, bottom, left])
            words: All words occuring in text, helpful for highlighting.
            highlight_word_index: Index of word to highlight (0-based, None to disable highlighting)
            highlight_color: RGB color for the highlighted word (defaults to text_color if None)
            highlight_size_multiplier: Font size multiplier for highlighted word
            highlight_bold_font: Path to bold font file for highlighted word (defaults to font_filename if None)

        Returns:
            Coordinates of the lower-right corner of the written text box (x, y)

        Raises:
            ValueError: If text is empty or parameters are invalid
            OutOfBoundsError: If text box would be outside image bounds
        """
        if not text:
            raise ValueError("Text cannot be empty")

        if font_size <= 0:
            raise ValueError("Font size must be positive")

        if background_padding < 0:
            raise ValueError("Background padding cannot be negative")

        if font_border_size < 0:
            raise ValueError("Font border size cannot be negative")

        # Validate highlighting parameters
        if highlight_word_index is not None:
            if not words:
                words = text.split()
            if highlight_word_index < 0 or highlight_word_index >= len(words):
                raise ValueError(
                    f"highlight_word_index {highlight_word_index} out of range for text with {len(words)} words"
                )

        if highlight_size_multiplier <= 0:
            raise ValueError("highlight_size_multiplier must be positive")

        # Set default highlight color if not provided
        if highlight_word_index is not None and highlight_color is None:
            highlight_color = text_color

        # Measure (single source of truth for box geometry), then render. When
        # a word will be highlighted, measure worst-case so the box reserves
        # room for the enlarged word -- otherwise stay byte-identical to the
        # plain base-font measurement.
        measure_mult = highlight_size_multiplier if highlight_word_index is not None else 1.0
        rect = self.measure_text_box(
            text=text,
            font_filename=font_filename,
            xy=xy,
            box_width=box_width,
            font_size=font_size,
            anchor=anchor,
            margin=margin,
            highlight_size_multiplier=measure_mult,
            highlight_bold_font=highlight_bold_font,
        )
        lines = list(rect.lines)
        if rect.height == 0:
            # No renderable lines (e.g. whitespace-only text); nothing to draw.
            return (int(rect.x), int(rect.y))
        box_width = rect.width
        x_pos, y_pos = rect.x, rect.y
        lines_height = rect.height
        if not rect.fits:
            raise OutOfBoundsError(
                f"Text box with size ({box_width}x{lines_height}) at position ({x_pos}, {y_pos}) is out of bounds!"
            )

        # Write lines. The line that holds the highlighted word is positioned
        # and advanced by its *true* (enlarged) extent via the shared
        # ``_highlighted_line_size`` -- the same numbers ``measure_text_box``
        # reserved -- so an enlarged word can never push the line out of the
        # box (hence out of the frame) regardless of alignment.
        current_text_height = y_pos
        word_index_offset = 0  # Track global word index across lines
        for line in lines:
            line_words = line.split()
            hl_local_index = -1
            if highlight_word_index is not None:
                line_end_word_index = word_index_offset + len(line_words) - 1
                if word_index_offset <= highlight_word_index <= line_end_word_index:
                    hl_local_index = highlight_word_index - word_index_offset

            if hl_local_index >= 0:
                line_w, line_h = self._highlighted_line_size(
                    line, font_filename, font_size, hl_local_index, highlight_size_multiplier, highlight_bold_font
                )
            else:
                line_w, line_h = self.get_text_dimensions(font_filename, font_size, line)

            # Calculate horizontal position based on alignment (true line width)
            if place == TextAlign.LEFT:
                x_left = x_pos
            elif place == TextAlign.RIGHT:
                x_left = x_pos + box_width - line_w
            elif place == TextAlign.CENTER:
                x_left = int(x_pos + ((box_width - line_w) / 2))
            else:
                valid_places = [e.value for e in TextAlign]
                raise ValueError(f"Place '{place}' is not supported. Must be one of: {', '.join(valid_places)}")

            if hl_local_index >= 0:
                self._write_line_with_highlight(
                    line=line,
                    font_filename=font_filename,
                    font_size=font_size,
                    font_border_size=font_border_size,
                    text_color=text_color,
                    highlight_color=highlight_color or (255, 255, 255),
                    highlight_size_multiplier=highlight_size_multiplier,
                    highlight_word_local_index=hl_local_index,
                    highlight_bold_font=highlight_bold_font,
                    x_left=int(x_left),
                    y_top=int(current_text_height),
                )
            else:
                # Write normal line without highlighting
                self.write_text(
                    text=line,
                    font_filename=font_filename,
                    xy=(x_left, current_text_height),
                    font_size=font_size,
                    font_border_size=font_border_size,
                    color=text_color,
                )

            word_index_offset += len(line_words)
            # Increment vertical position for next line (true line height)
            current_text_height += line_h

        # Add background color for the text if specified
        if background_color is not None:
            if len(background_color) != 4:
                raise ValueError(f"Text background color {background_color} must be RGBA (4 values)!")

            img = self.img_array

            # Find bounding rectangle for written text
            # Skip if the box is empty
            if y_pos >= current_text_height or x_pos >= x_pos + box_width:
                return (int(x_pos + box_width), int(current_text_height))

            # Get the slice of the image containing the text box
            box_slice = img[int(y_pos) : int(current_text_height), int(x_pos) : int(x_pos + box_width)]
            if box_slice.size == 0:  # Empty slice
                return (int(x_pos + box_width), int(current_text_height))

            # Create mask of non-zero pixels (text)
            text_mask = np.any(box_slice != 0, axis=2).astype(np.uint8)
            if not isinstance(text_mask, np.ndarray):
                raise TypeError(f"The returned text mask is of type {type(text_mask)}, but it should be numpy array!")

            # If no text pixels found, return without background
            if not np.any(text_mask):
                return (int(x_pos + box_width), int(current_text_height))

            # Find the smallest rectangle containing text
            try:
                xmin, xmax, ymin, ymax = self._find_smallest_bounding_rect(text_mask)
            except ValueError:
                # _find_smallest_bounding_rect raises ValueError for empty mask
                xmin, xmax, ymin, ymax = 0, box_slice.shape[1] - 1, 0, box_slice.shape[0] - 1

            # Get global bounding box position
            xmin = int(xmin + x_pos - background_padding)
            xmax = int(xmax + x_pos + background_padding)
            ymin = int(ymin + y_pos - background_padding)
            ymax = int(ymax + y_pos + background_padding)

            # Make sure we are inside image bounds
            xmin = max(0, xmin)
            ymin = max(0, ymin)
            xmax = min(xmax, self.image_size[1])
            ymax = min(ymax, self.image_size[0])

            # Skip if bounding box is invalid
            if xmin >= xmax or ymin >= ymax:
                return (int(x_pos + box_width), int(current_text_height))

            # Slice the bounding box and find text mask
            bbox_slice = img[ymin:ymax, xmin:xmax]
            if bbox_slice.size == 0:  # Empty slice
                return (int(x_pos + box_width), int(current_text_height))

            bbox_text_mask = np.any(bbox_slice != 0, axis=2).astype(np.uint8)

            # Add background color outside of text
            bbox_slice[~bbox_text_mask.astype(bool)] = background_color

            # Handle semi-transparent pixels for smooth text blending
            text_slice = bbox_slice[bbox_text_mask.astype(bool)]
            if text_slice.size > 0:
                text_background = text_slice[:, :3] * (np.expand_dims(text_slice[:, -1], axis=1) / 255)
                color_background = (1 - (np.expand_dims(text_slice[:, -1], axis=1) / 255)) * background_color
                faded_background = text_background[:, :3] + color_background[:, :3]
                text_slice[:, :3] = faded_background
                text_slice[:, -1] = 255  # Full opacity
                bbox_slice[bbox_text_mask.astype(bool)] = text_slice

            # Update the image with the background color
            self.image = Image.fromarray(img)

        return (int(x_pos + box_width), int(current_text_height))

    def _highlight_font(
        self,
        font_filename: str | None,
        font_size: int,
        highlight_size_multiplier: float,
        highlight_bold_font: str | None,
    ) -> tuple[str | None, int, int, int]:
        """Resolve the enlarged-word basics once.

        Returns ``(font_file, font_size, baseline_offset, space_width)`` -- the
        single definition of the highlight constants, shared by the per-word
        layout (render / exact-size path) and the worst-case extent (measure
        path) so those paths cannot drift apart on the fundamentals.
        """
        hl_font_size = int(font_size * highlight_size_multiplier)
        hl_font_file = highlight_bold_font if highlight_bold_font is not None else font_filename
        baseline_offset = self._get_font_baseline_offset(font_filename, font_size, hl_font_file, hl_font_size)
        space_width = self.get_text_dimensions(font_filename, font_size, " ")[0]
        return hl_font_file, hl_font_size, baseline_offset, space_width

    def _layout_highlighted_line(
        self,
        line: str,
        font_filename: str | None,
        font_size: int,
        highlight_word_local_index: int,
        highlight_size_multiplier: float,
        highlight_bold_font: str | None,
    ) -> list[_WordPlacement]:
        """Per-word placement for ``line`` with one word enlarged.

        The single source of truth for the highlighted-line advance (enlarged
        font size, bold-font swap, base-size inter-word space, baseline
        offset). Both :meth:`_highlighted_line_size` (measuring the line that
        actually owns the highlight) and :meth:`_write_line_with_highlight`
        (rendering it) consume this list, so the reserved box and the drawn
        pixels agree by construction.

        Reached only for the line that owns the highlighted word, so
        ``highlight_word_local_index`` is in range; degenerate inputs are
        handled by the callers' own guards.
        """
        words = line.split()
        hl_font_file, hl_font_size, baseline_offset, space_width = self._highlight_font(
            font_filename, font_size, highlight_size_multiplier, highlight_bold_font
        )
        placements: list[_WordPlacement] = []
        dx = 0
        for i, word in enumerate(words):
            is_hl = i == highlight_word_local_index
            wf = hl_font_file if is_hl else font_filename
            ws = hl_font_size if is_hl else font_size
            w, h = self.get_text_dimensions(wf, ws, word)
            placements.append(
                _WordPlacement(
                    word=word,
                    font_filename=wf,
                    font_size=ws,
                    width=w,
                    height=h,
                    dx=dx,
                    dy=baseline_offset if is_hl else 0,
                    is_highlighted=is_hl,
                )
            )
            dx += w
            if i < len(words) - 1:
                dx += space_width
        return placements

    def _highlighted_line_size(
        self,
        line: str,
        font_filename: str | None,
        font_size: int,
        highlight_word_local_index: int,
        highlight_size_multiplier: float,
        highlight_bold_font: str | None,
    ) -> tuple[int, int]:
        """Rendered (width, height) of ``line`` with one *specific* word enlarged.

        A reduction of the shared :meth:`_layout_highlighted_line`, so it is
        exact w.r.t. the renderer by construction. Used to position/advance
        the line that owns the highlighted word. ``highlight_word_local_index``
        out of range falls back to the plain line size -- exactly what the
        renderer's own guard ends up drawing.
        """
        words = line.split()
        if not words:
            return (0, 0)
        if not (0 <= highlight_word_local_index < len(words)):
            return self.get_text_dimensions(font_filename, font_size, line)
        placements = self._layout_highlighted_line(
            line, font_filename, font_size, highlight_word_local_index, highlight_size_multiplier, highlight_bold_font
        )
        width = max(p.dx + p.width for p in placements)
        # ``min(0, ...)`` / ``max(0, ...)`` stay defensive for a *shrinking*
        # highlight (multiplier < 1 -> negative baseline offset, the word
        # rides above the line). The subtitle measure path clamps the
        # multiplier to >= 1 so there ``top`` is always 0, but
        # ``write_text_box`` forwards the raw multiplier, so keep the floor.
        top = min([0, *(p.dy for p in placements)])
        bottom = max([0, *(p.dy + p.height for p in placements)])
        return (width, bottom - top)

    def _highlighted_line_max_extent(
        self,
        line: str,
        font_filename: str | None,
        font_size: int,
        highlight_size_multiplier: float,
        highlight_bold_font: str | None,
    ) -> tuple[int, int]:
        """Worst-case (width, height) over *any* word being the enlarged one.

        Equal to ``max`` of :meth:`_highlighted_line_size` across every word
        position -- the envelope an animated highlight needs -- but in a
        single O(words) pass instead of O(words^2): only *which* word is
        enlarged varies, so the base metrics are shared and the extremes are
        closed-form. Uses the same :meth:`_highlight_font` constants as the
        layout, so this envelope can never under-reserve what the renderer
        draws (it over-reserves only in the safe direction).
        """
        words = line.split()
        if not words:
            return self.get_text_dimensions(font_filename, font_size, line)
        hl_font_file, hl_font_size, baseline_offset, space_width = self._highlight_font(
            font_filename, font_size, highlight_size_multiplier, highlight_bold_font
        )
        base = [self.get_text_dimensions(font_filename, font_size, w) for w in words]
        enlarged = [self.get_text_dimensions(hl_font_file, hl_font_size, w) for w in words]
        # width_k = (sum of base widths + spaces) - base_w[k] + enlarged_w[k];
        # the worst k just maximizes the (enlarged - base) swap.
        base_total = sum(w for w, _ in base) + space_width * (len(words) - 1)
        width = base_total + max(ew - bw for (bw, _), (ew, _) in zip(base, enlarged))
        # Non-highlighted words sit at dy=0, the enlarged one at
        # dy=baseline_offset; the worst line is the tallest base word vs. the
        # tallest enlarged word lifted by the baseline offset.
        top = min(0, baseline_offset)
        bottom = max([0, *(h for _, h in base), baseline_offset + max(h for _, h in enlarged)])
        return (width, bottom - top)

    def _write_line_with_highlight(
        self,
        line: str,
        font_filename: str | None,
        font_size: int,
        font_border_size: int,
        text_color: RGBColor,
        highlight_color: RGBColor,
        highlight_size_multiplier: float,
        highlight_word_local_index: int,
        highlight_bold_font: str | None,
        x_left: int,
        y_top: int,
    ) -> None:
        """
        Write a line of text with one word highlighted, word-by-word with baseline alignment.

        Draws the placements from the shared :meth:`_layout_highlighted_line`,
        so every pixel lands exactly where :meth:`measure_text_box` reserved
        room for it (measurement and rendering use the same geometry).

        Args:
            line: The text line to render
            font_filename: Path to the font file
            font_size: Base font size in points
            font_border_size: Size of border around text in pixels (0 for no border)
            text_color: RGB color for normal text
            highlight_color: RGB color for highlighted word
            highlight_size_multiplier: Font size multiplier for highlighted word
            highlight_word_local_index: Index of word to highlight within this line (0-based)
            highlight_bold_font: Path to bold font file for highlighted word (defaults to font_filename if None)
            x_left: Left x position for the line
            y_top: Top y position for the line
        """
        words = line.split()
        if highlight_word_local_index >= len(words):
            return  # Safety check: nothing to draw (matches the measure fallback)

        for p in self._layout_highlighted_line(
            line, font_filename, font_size, highlight_word_local_index, highlight_size_multiplier, highlight_bold_font
        ):
            self.write_text(
                text=p.word,
                font_filename=p.font_filename,
                xy=(x_left + p.dx, y_top + p.dy),
                font_size=p.font_size,
                font_border_size=font_border_size,
                color=highlight_color if p.is_highlighted else text_color,
            )

    def _find_smallest_bounding_rect(self, mask: np.ndarray) -> tuple[int, int, int, int]:
        """
        Find the smallest bounding rectangle containing non-zero values in the mask.

        Args:
            mask: 2D numpy array with non-zero values representing pixels of interest

        Returns:
            Tuple of (xmin, xmax, ymin, ymax) coordinates

        Raises:
            ValueError: If mask is empty or has no non-zero values
        """
        if mask.size == 0:
            raise ValueError("Mask is empty")

        # Check if mask has any non-zero values
        if not np.any(mask):
            raise ValueError("Mask has no non-zero values")

        rows = np.any(mask, axis=1)
        cols = np.any(mask, axis=0)

        # Find indices of first and last True values
        row_indices = np.where(rows)[0]
        col_indices = np.where(cols)[0]

        # Handle empty results
        if len(row_indices) == 0 or len(col_indices) == 0:
            raise ValueError("No bounding rectangle found")

        ymin, ymax = row_indices[[0, -1]]
        xmin, xmax = col_indices[[0, -1]]

        return xmin, xmax, ymin, ymax

img_array property

img_array: ndarray

Convert the PIL Image to a numpy array.

__init__

__init__(
    image_size: tuple[int, int] = (1920, 1080),
    mode: str = "RGBA",
    background: RGBAColor = (0, 0, 0, 0),
)

Initialize an image for text rendering.

Parameters:

Name	Type	Description	Default
image_size	tuple[int, int]	Dimensions of the image (height, width) - NumPy convention	(1920, 1080)
mode	str	Image mode (RGB, RGBA, etc.)	'RGBA'
background	RGBAColor	Background color with alpha channel	(0, 0, 0, 0)

Raises:

Type	Description
ValueError	If image_size dimensions are not positive

Source code in src/videopython/base/image_text.py

def __init__(
    self,
    image_size: tuple[int, int] = (1920, 1080),  # (height, width) - NumPy convention
    mode: str = "RGBA",
    background: RGBAColor = (0, 0, 0, 0),  # Transparent background
):
    """
    Initialize an image for text rendering.

    Args:
        image_size: Dimensions of the image (height, width) - NumPy convention
        mode: Image mode (RGB, RGBA, etc.)
        background: Background color with alpha channel

    Raises:
        ValueError: If image_size dimensions are not positive
    """
    if image_size[0] <= 0 or image_size[1] <= 0:
        raise ValueError("Image dimensions must be positive")

    if len(background) != 4:
        raise ValueError("Background color must be RGBA (4 values)")

    self.image_size = image_size  # Stored as (height, width)
    # PIL uses (width, height), so we reverse for Image.new
    self.image = Image.new(mode, (image_size[1], image_size[0]), color=background)
    self._draw = ImageDraw.Draw(self.image)
    self._font_cache: dict[tuple[str | None, int], ImageFont.FreeTypeFont | ImageFont.ImageFont] = {}

save

save(filename: str) -> None

Save the image to a file.

Source code in src/videopython/base/image_text.py

def save(self, filename: str) -> None:
    """Save the image to a file."""
    if not filename:
        raise ValueError("Filename cannot be empty")
    self.image.save(filename)

write_text

write_text(
    text: str,
    font_filename: str | None,
    xy: PositionType,
    font_size: int | None = 11,
    font_border_size: int = 0,
    color: RGBColor = (0, 0, 0),
    max_width: int | None = None,
    max_height: int | None = None,
    anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
    margin: MarginType = 0,
) -> tuple[int, int]

Write text to the image with advanced positioning options.

Parameters:

Name	Type	Description	Default
text	str	Text to be written	required
font_filename	str | None	Path to the font file	required
xy	PositionType	Position (x,y) either as absolute pixels (int) or relative to frame (float 0-1)	required
font_size	int | None	Size of the font in points, or None to auto-calculate	11
font_border_size	int	Size of border around text in pixels (0 for no border)	0
color	RGBColor	RGB color of the text	(0, 0, 0)
max_width	int | None	Maximum width for auto font sizing	None
max_height	int | None	Maximum height for auto font sizing	None
anchor	AnchorPoint	Which part of the text to anchor at the position	TOP_LEFT
margin	MarginType	Margin in pixels (single value or [top, right, bottom, left])	0

Returns:

Type	Description
tuple[int, int]	Dimensions of the rendered text (width, height)

Raises:

Type	Description
ValueError	If text is empty or font parameters are invalid
OutOfBoundsError	If the text would be rendered outside the image bounds

Source code in src/videopython/base/image_text.py

def write_text(
    self,
    text: str,
    font_filename: str | None,
    xy: PositionType,
    font_size: int | None = 11,
    font_border_size: int = 0,
    color: RGBColor = (0, 0, 0),
    max_width: int | None = None,
    max_height: int | None = None,
    anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
    margin: MarginType = 0,
) -> tuple[int, int]:
    """
    Write text to the image with advanced positioning options.

    Args:
        text: Text to be written
        font_filename: Path to the font file
        xy: Position (x,y) either as absolute pixels (int) or relative to frame (float 0-1)
        font_size: Size of the font in points, or None to auto-calculate
        font_border_size: Size of border around text in pixels (0 for no border)
        color: RGB color of the text
        max_width: Maximum width for auto font sizing
        max_height: Maximum height for auto font sizing
        anchor: Which part of the text to anchor at the position
        margin: Margin in pixels (single value or [top, right, bottom, left])

    Returns:
        Dimensions of the rendered text (width, height)

    Raises:
        ValueError: If text is empty or font parameters are invalid
        OutOfBoundsError: If the text would be rendered outside the image bounds
    """
    if not text:
        raise ValueError("Text cannot be empty")

    if font_size is not None and font_size <= 0:
        raise ValueError("Font size must be positive")

    if font_border_size < 0:
        raise ValueError("Font border size cannot be negative")

    if font_size is None and (max_width is None or max_height is None):
        raise ValueError("Must set either `font_size`, or both `max_width` and `max_height`!")
    elif font_size is None:
        font_size = self._get_font_size(text, font_filename, max_width, max_height)

    # Get or create the font object (with caching)
    font = self._get_font(font_filename, font_size)
    text_dimensions = self.get_text_dimensions(font_filename, font_size, text)

    # Calculate the position based on anchor point and margins
    x, y = self._calculate_position(text_dimensions, xy, anchor, margin)

    # Verify text will fit within bounds
    if x < 0 or y < 0 or x + text_dimensions[0] > self.image_size[1] or y + text_dimensions[1] > self.image_size[0]:
        raise OutOfBoundsError(f"Text with size {text_dimensions} at position ({x}, {y}) is out of bounds!")

    # Draw border if requested
    if font_border_size > 0:
        # Draw text border by drawing text in multiple positions around the main text
        for border_x in range(-font_border_size, font_border_size + 1):
            for border_y in range(-font_border_size, font_border_size + 1):
                if border_x != 0 or border_y != 0:  # Skip the center position
                    self._draw.text((x + border_x, y + border_y), text, font=font, fill=(0, 0, 0))

    # Draw the main text on top
    self._draw.text((x, y), text, font=font, fill=color)
    return text_dimensions

get_text_dimensions

get_text_dimensions(
    font_filename: str | None, font_size: int, text: str
) -> tuple[int, int]

Return dimensions (width, height) of the rendered text.

Parameters:

Name	Type	Description	Default
font_filename	str | None	Path to the font file	required
font_size	int	Size of the font in points	required
text	str	Text to measure	required

Returns:

Type	Description
tuple[int, int]	Tuple of (width, height) for the rendered text

Raises:

Type	Description
ValueError	If font parameters are invalid or text is empty

Source code in src/videopython/base/image_text.py

def get_text_dimensions(self, font_filename: str | None, font_size: int, text: str) -> tuple[int, int]:
    """
    Return dimensions (width, height) of the rendered text.

    Args:
        font_filename: Path to the font file
        font_size: Size of the font in points
        text: Text to measure

    Returns:
        Tuple of (width, height) for the rendered text

    Raises:
        ValueError: If font parameters are invalid or text is empty
    """
    if not text:
        return (0, 0)  # Empty text has no dimensions

    if font_size <= 0:
        raise ValueError("Font size must be positive")

    font = self._get_font(font_filename, font_size)
    try:
        bbox = font.getbbox(text)
        if bbox is None:
            return (0, 0)  # Handle case where getbbox returns None
        return bbox[2:] if len(bbox) >= 4 else (0, 0)
    except Exception as e:
        raise ValueError(f"Error measuring text: {str(e)}")

available_region

available_region(
    margin: MarginType = 0,
) -> tuple[int, int, int, int]

The drawable area inside margin as (left, top, width, height).

Single source of truth for margin-inset geometry: used by :meth:measure_text_box and by callers that need to clamp a box within the margins without re-deriving the margin math.

Source code in src/videopython/base/image_text.py

def available_region(self, margin: MarginType = 0) -> tuple[int, int, int, int]:
    """The drawable area inside ``margin`` as ``(left, top, width, height)``.

    Single source of truth for margin-inset geometry: used by
    :meth:`measure_text_box` and by callers that need to clamp a box
    within the margins without re-deriving the margin math.
    """
    margin_top, margin_right, margin_bottom, margin_left = self._process_margin(margin)
    available_width = self.image_size[1] - margin_left - margin_right
    available_height = self.image_size[0] - margin_top - margin_bottom
    return margin_left, margin_top, available_width, available_height

measure_text_box

measure_text_box(
    text: str,
    font_filename: str | None,
    xy: PositionType,
    box_width: int | float | None = None,
    font_size: int = 11,
    anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
    margin: MarginType = 0,
    highlight_size_multiplier: float = 1.0,
    highlight_bold_font: str | None = None,
) -> TextBoxRect

Measure where a wrapped text box would land, without drawing it.

Pure: resolves margins/box-width/position, wraps the text, applies the anchor, and bounds-checks against the image — the exact math :meth:write_text_box used to do inline.

highlight_size_multiplier > 1 makes the measurement worst-case for an animated highlight (any word may be the enlarged one over the cue's lifetime): wrapping reserves room so even an enlarged word keeps its line within box_width, and height uses each line's tallest possible highlighted variant. With the default 1.0 the result is byte-identical to the plain base-font measurement, so existing callers and place (alignment) are unaffected.

Returns:

Name	Type	Description
A	TextBoxRect	class:TextBoxRect. fits is False when the box would
	TextBoxRect	fall outside the image bounds (the condition that makes
	TextBoxRect	meth:write_text_box raise :class:OutOfBoundsError).

Raises:

Type	Description
ValueError	If text is empty, font_size is not positive, or an absolute box_width is not positive.

Source code in src/videopython/base/image_text.py

def measure_text_box(
    self,
    text: str,
    font_filename: str | None,
    xy: PositionType,
    box_width: int | float | None = None,
    font_size: int = 11,
    anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
    margin: MarginType = 0,
    highlight_size_multiplier: float = 1.0,
    highlight_bold_font: str | None = None,
) -> TextBoxRect:
    """Measure where a wrapped text box would land, without drawing it.

    Pure: resolves margins/box-width/position, wraps the text, applies the
    anchor, and bounds-checks against the image — the exact math
    :meth:`write_text_box` used to do inline.

    ``highlight_size_multiplier > 1`` makes the measurement worst-case for
    an *animated* highlight (any word may be the enlarged one over the
    cue's lifetime): wrapping reserves room so even an enlarged word keeps
    its line within ``box_width``, and ``height`` uses each line's tallest
    possible highlighted variant. With the default ``1.0`` the result is
    byte-identical to the plain base-font measurement, so existing callers
    and ``place`` (alignment) are unaffected.

    Returns:
        A :class:`TextBoxRect`. ``fits`` is ``False`` when the box would
        fall outside the image bounds (the condition that makes
        :meth:`write_text_box` raise :class:`OutOfBoundsError`).

    Raises:
        ValueError: If ``text`` is empty, ``font_size`` is not positive,
            or an absolute ``box_width`` is not positive.
    """
    if not text:
        raise ValueError("Text cannot be empty")

    if font_size <= 0:
        raise ValueError("Font size must be positive")

    # Process margins to determine available area (shared with callers
    # that clamp boxes inside the margins -- see ``available_region``).
    margin_left, margin_top, available_width, available_height = self.available_region(margin)

    # Handle relative box width
    if box_width is None:
        box_width = available_width
    elif isinstance(box_width, float) and 0 < box_width <= 1:
        box_width = int(available_width * box_width)
    elif isinstance(box_width, int) and box_width <= 0:
        raise ValueError("Box width must be positive")

    # Calculate initial position based on margin and anchor before splitting text
    x_pos, y_pos = self._convert_position(xy, margin_top, margin_left, available_width, available_height)

    # Wrap at the real box width (same as the renderer).
    lines = self._split_lines_by_width(text, font_filename, font_size, int(box_width))

    # Per-line extent. With an animated highlight any word may be the
    # enlarged one over the cue's lifetime, so each line contributes the
    # widest/tallest variant it could ever render as.
    # ``_highlighted_line_max_extent`` derives that envelope from the same
    # per-word geometry the renderer uses (single source of truth).
    hl_mult = max(1.0, highlight_size_multiplier)
    content_width = 0
    lines_height = 0
    for line in lines:
        if hl_mult > 1.0:
            line_w, line_h = self._highlighted_line_max_extent(
                line, font_filename, font_size, hl_mult, highlight_bold_font
            )
        else:
            line_w, line_h = self.get_text_dimensions(font_filename, font_size, line)
        content_width = max(content_width, line_w)
        lines_height += line_h
    if lines_height == 0:
        # No renderable lines (e.g. whitespace-only text); position is the
        # unadjusted insertion point and the box trivially "fits".
        return TextBoxRect(
            x=x_pos, y=y_pos, width=box_width, height=0, fits=True, lines=tuple(lines), content_width=0
        )

    # Final position calculation based on anchor point
    if anchor in AnchorPoint.center_anchors():
        x_pos -= box_width // 2
    elif anchor in AnchorPoint.right_anchors():
        x_pos -= box_width

    if anchor in AnchorPoint.middle_anchors():
        y_pos -= lines_height // 2
    elif anchor in AnchorPoint.bottom_anchors():
        y_pos -= lines_height

    fits = not (
        x_pos < 0
        or y_pos < 0
        or x_pos + box_width > self.image_size[1]
        or y_pos + lines_height > self.image_size[0]
    )
    return TextBoxRect(
        x=x_pos,
        y=y_pos,
        width=box_width,
        height=lines_height,
        fits=fits,
        lines=tuple(lines),
        content_width=content_width,
    )

write_text_box

write_text_box(
    text: str,
    font_filename: str | None,
    xy: PositionType,
    box_width: int | float | None = None,
    font_size: int = 11,
    font_border_size: int = 0,
    text_color: RGBColor = (0, 0, 0),
    background_color: RGBAColor | None = None,
    background_padding: int = 0,
    place: TextAlign = TextAlign.LEFT,
    anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
    margin: MarginType = 0,
    words: list[str] | None = None,
    highlight_word_index: int | None = None,
    highlight_color: RGBColor | None = None,
    highlight_size_multiplier: float = DEFAULT_HIGHLIGHT_SIZE_MULTIPLIER,
    highlight_bold_font: str | None = None,
) -> tuple[int, int]

Write text in a box with advanced positioning and alignment options.

Parameters:

Name	Type	Description	Default
text	str	Text to be written inside the box	required
font_filename	str | None	Path to the font file	required
xy	PositionType	Position (x,y) either as absolute pixels (int) or relative to frame (float 0-1)	required
box_width	int | float | None	Width of the box in pixels (int) or relative to frame width (float 0-1)	None
font_size	int	Font size in points	11
font_border_size	int	Size of border around text in pixels (0 for no border)	0
text_color	RGBColor	RGB color of the text	(0, 0, 0)
background_color	RGBAColor | None	If set, adds background color to the text box. Expects RGBA values.	None
background_padding	int	Number of padding pixels to add when adding text background color	0
place	TextAlign	Text alignment within the box (TextAlign.LEFT, TextAlign.RIGHT, TextAlign.CENTER)	LEFT
anchor	AnchorPoint	Which part of the text box to anchor at the position	TOP_LEFT
margin	MarginType	Margin in pixels (single value or [top, right, bottom, left])	0
words	list[str] | None	All words occuring in text, helpful for highlighting.	None
highlight_word_index	int | None	Index of word to highlight (0-based, None to disable highlighting)	None
highlight_color	RGBColor | None	RGB color for the highlighted word (defaults to text_color if None)	None
highlight_size_multiplier	float	Font size multiplier for highlighted word	DEFAULT_HIGHLIGHT_SIZE_MULTIPLIER
highlight_bold_font	str | None	Path to bold font file for highlighted word (defaults to font_filename if None)	None

Returns:

Type	Description
tuple[int, int]	Coordinates of the lower-right corner of the written text box (x, y)

Raises:

Type	Description
ValueError	If text is empty or parameters are invalid
OutOfBoundsError	If text box would be outside image bounds

Source code in src/videopython/base/image_text.py

def write_text_box(
    self,
    text: str,
    font_filename: str | None,
    xy: PositionType,
    box_width: int | float | None = None,
    font_size: int = 11,
    font_border_size: int = 0,
    text_color: RGBColor = (0, 0, 0),
    background_color: RGBAColor | None = None,
    background_padding: int = 0,
    place: TextAlign = TextAlign.LEFT,
    anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
    margin: MarginType = 0,
    words: list[str] | None = None,
    highlight_word_index: int | None = None,
    highlight_color: RGBColor | None = None,
    highlight_size_multiplier: float = DEFAULT_HIGHLIGHT_SIZE_MULTIPLIER,
    highlight_bold_font: str | None = None,
) -> tuple[int, int]:
    """
    Write text in a box with advanced positioning and alignment options.

    Args:
        text: Text to be written inside the box
        font_filename: Path to the font file
        xy: Position (x,y) either as absolute pixels (int) or relative to frame (float 0-1)
        box_width: Width of the box in pixels (int) or relative to frame width (float 0-1)
        font_size: Font size in points
        font_border_size: Size of border around text in pixels (0 for no border)
        text_color: RGB color of the text
        background_color: If set, adds background color to the text box. Expects RGBA values.
        background_padding: Number of padding pixels to add when adding text background color
        place: Text alignment within the box (TextAlign.LEFT, TextAlign.RIGHT, TextAlign.CENTER)
        anchor: Which part of the text box to anchor at the position
        margin: Margin in pixels (single value or [top, right, bottom, left])
        words: All words occuring in text, helpful for highlighting.
        highlight_word_index: Index of word to highlight (0-based, None to disable highlighting)
        highlight_color: RGB color for the highlighted word (defaults to text_color if None)
        highlight_size_multiplier: Font size multiplier for highlighted word
        highlight_bold_font: Path to bold font file for highlighted word (defaults to font_filename if None)

    Returns:
        Coordinates of the lower-right corner of the written text box (x, y)

    Raises:
        ValueError: If text is empty or parameters are invalid
        OutOfBoundsError: If text box would be outside image bounds
    """
    if not text:
        raise ValueError("Text cannot be empty")

    if font_size <= 0:
        raise ValueError("Font size must be positive")

    if background_padding < 0:
        raise ValueError("Background padding cannot be negative")

    if font_border_size < 0:
        raise ValueError("Font border size cannot be negative")

    # Validate highlighting parameters
    if highlight_word_index is not None:
        if not words:
            words = text.split()
        if highlight_word_index < 0 or highlight_word_index >= len(words):
            raise ValueError(
                f"highlight_word_index {highlight_word_index} out of range for text with {len(words)} words"
            )

    if highlight_size_multiplier <= 0:
        raise ValueError("highlight_size_multiplier must be positive")

    # Set default highlight color if not provided
    if highlight_word_index is not None and highlight_color is None:
        highlight_color = text_color

    # Measure (single source of truth for box geometry), then render. When
    # a word will be highlighted, measure worst-case so the box reserves
    # room for the enlarged word -- otherwise stay byte-identical to the
    # plain base-font measurement.
    measure_mult = highlight_size_multiplier if highlight_word_index is not None else 1.0
    rect = self.measure_text_box(
        text=text,
        font_filename=font_filename,
        xy=xy,
        box_width=box_width,
        font_size=font_size,
        anchor=anchor,
        margin=margin,
        highlight_size_multiplier=measure_mult,
        highlight_bold_font=highlight_bold_font,
    )
    lines = list(rect.lines)
    if rect.height == 0:
        # No renderable lines (e.g. whitespace-only text); nothing to draw.
        return (int(rect.x), int(rect.y))
    box_width = rect.width
    x_pos, y_pos = rect.x, rect.y
    lines_height = rect.height
    if not rect.fits:
        raise OutOfBoundsError(
            f"Text box with size ({box_width}x{lines_height}) at position ({x_pos}, {y_pos}) is out of bounds!"
        )

    # Write lines. The line that holds the highlighted word is positioned
    # and advanced by its *true* (enlarged) extent via the shared
    # ``_highlighted_line_size`` -- the same numbers ``measure_text_box``
    # reserved -- so an enlarged word can never push the line out of the
    # box (hence out of the frame) regardless of alignment.
    current_text_height = y_pos
    word_index_offset = 0  # Track global word index across lines
    for line in lines:
        line_words = line.split()
        hl_local_index = -1
        if highlight_word_index is not None:
            line_end_word_index = word_index_offset + len(line_words) - 1
            if word_index_offset <= highlight_word_index <= line_end_word_index:
                hl_local_index = highlight_word_index - word_index_offset

        if hl_local_index >= 0:
            line_w, line_h = self._highlighted_line_size(
                line, font_filename, font_size, hl_local_index, highlight_size_multiplier, highlight_bold_font
            )
        else:
            line_w, line_h = self.get_text_dimensions(font_filename, font_size, line)

        # Calculate horizontal position based on alignment (true line width)
        if place == TextAlign.LEFT:
            x_left = x_pos
        elif place == TextAlign.RIGHT:
            x_left = x_pos + box_width - line_w
        elif place == TextAlign.CENTER:
            x_left = int(x_pos + ((box_width - line_w) / 2))
        else:
            valid_places = [e.value for e in TextAlign]
            raise ValueError(f"Place '{place}' is not supported. Must be one of: {', '.join(valid_places)}")

        if hl_local_index >= 0:
            self._write_line_with_highlight(
                line=line,
                font_filename=font_filename,
                font_size=font_size,
                font_border_size=font_border_size,
                text_color=text_color,
                highlight_color=highlight_color or (255, 255, 255),
                highlight_size_multiplier=highlight_size_multiplier,
                highlight_word_local_index=hl_local_index,
                highlight_bold_font=highlight_bold_font,
                x_left=int(x_left),
                y_top=int(current_text_height),
            )
        else:
            # Write normal line without highlighting
            self.write_text(
                text=line,
                font_filename=font_filename,
                xy=(x_left, current_text_height),
                font_size=font_size,
                font_border_size=font_border_size,
                color=text_color,
            )

        word_index_offset += len(line_words)
        # Increment vertical position for next line (true line height)
        current_text_height += line_h

    # Add background color for the text if specified
    if background_color is not None:
        if len(background_color) != 4:
            raise ValueError(f"Text background color {background_color} must be RGBA (4 values)!")

        img = self.img_array

        # Find bounding rectangle for written text
        # Skip if the box is empty
        if y_pos >= current_text_height or x_pos >= x_pos + box_width:
            return (int(x_pos + box_width), int(current_text_height))

        # Get the slice of the image containing the text box
        box_slice = img[int(y_pos) : int(current_text_height), int(x_pos) : int(x_pos + box_width)]
        if box_slice.size == 0:  # Empty slice
            return (int(x_pos + box_width), int(current_text_height))

        # Create mask of non-zero pixels (text)
        text_mask = np.any(box_slice != 0, axis=2).astype(np.uint8)
        if not isinstance(text_mask, np.ndarray):
            raise TypeError(f"The returned text mask is of type {type(text_mask)}, but it should be numpy array!")

        # If no text pixels found, return without background
        if not np.any(text_mask):
            return (int(x_pos + box_width), int(current_text_height))

        # Find the smallest rectangle containing text
        try:
            xmin, xmax, ymin, ymax = self._find_smallest_bounding_rect(text_mask)
        except ValueError:
            # _find_smallest_bounding_rect raises ValueError for empty mask
            xmin, xmax, ymin, ymax = 0, box_slice.shape[1] - 1, 0, box_slice.shape[0] - 1

        # Get global bounding box position
        xmin = int(xmin + x_pos - background_padding)
        xmax = int(xmax + x_pos + background_padding)
        ymin = int(ymin + y_pos - background_padding)
        ymax = int(ymax + y_pos + background_padding)

        # Make sure we are inside image bounds
        xmin = max(0, xmin)
        ymin = max(0, ymin)
        xmax = min(xmax, self.image_size[1])
        ymax = min(ymax, self.image_size[0])

        # Skip if bounding box is invalid
        if xmin >= xmax or ymin >= ymax:
            return (int(x_pos + box_width), int(current_text_height))

        # Slice the bounding box and find text mask
        bbox_slice = img[ymin:ymax, xmin:xmax]
        if bbox_slice.size == 0:  # Empty slice
            return (int(x_pos + box_width), int(current_text_height))

        bbox_text_mask = np.any(bbox_slice != 0, axis=2).astype(np.uint8)

        # Add background color outside of text
        bbox_slice[~bbox_text_mask.astype(bool)] = background_color

        # Handle semi-transparent pixels for smooth text blending
        text_slice = bbox_slice[bbox_text_mask.astype(bool)]
        if text_slice.size > 0:
            text_background = text_slice[:, :3] * (np.expand_dims(text_slice[:, -1], axis=1) / 255)
            color_background = (1 - (np.expand_dims(text_slice[:, -1], axis=1) / 255)) * background_color
            faded_background = text_background[:, :3] + color_background[:, :3]
            text_slice[:, :3] = faded_background
            text_slice[:, -1] = 255  # Full opacity
            bbox_slice[bbox_text_mask.astype(bool)] = text_slice

        # Update the image with the background color
        self.image = Image.fromarray(img)

    return (int(x_pos + box_width), int(current_text_height))

TextAlign

TextAlign

Bases: str, Enum

Defines text alignment options for positioning within containers.

Source code in src/videopython/base/image_text.py

class TextAlign(str, Enum):
    """Defines text alignment options for positioning within containers."""

    LEFT = "left"
    RIGHT = "right"
    CENTER = "center"

AnchorPoint

AnchorPoint

Bases: str, Enum

Defines anchor points for positioning text elements.

Source code in src/videopython/base/image_text.py

class AnchorPoint(str, Enum):
    """Defines anchor points for positioning text elements."""

    TOP_LEFT = "top-left"
    TOP_CENTER = "top-center"
    TOP_RIGHT = "top-right"
    CENTER_LEFT = "center-left"
    CENTER = "center"
    CENTER_RIGHT = "center-right"
    BOTTOM_LEFT = "bottom-left"
    BOTTOM_CENTER = "bottom-center"
    BOTTOM_RIGHT = "bottom-right"

    # Group anchor points by their horizontal position
    @classmethod
    def left_anchors(cls) -> tuple["AnchorPoint", ...]:
        return (cls.TOP_LEFT, cls.CENTER_LEFT, cls.BOTTOM_LEFT)

    @classmethod
    def center_anchors(cls) -> tuple["AnchorPoint", ...]:
        return (cls.TOP_CENTER, cls.CENTER, cls.BOTTOM_CENTER)

    @classmethod
    def right_anchors(cls) -> tuple["AnchorPoint", ...]:
        return (cls.TOP_RIGHT, cls.CENTER_RIGHT, cls.BOTTOM_RIGHT)

    # Group anchor points by their vertical position
    @classmethod
    def top_anchors(cls) -> tuple["AnchorPoint", ...]:
        return (cls.TOP_LEFT, cls.TOP_CENTER, cls.TOP_RIGHT)

    @classmethod
    def middle_anchors(cls) -> tuple["AnchorPoint", ...]:
        return (cls.CENTER_LEFT, cls.CENTER, cls.CENTER_RIGHT)

    @classmethod
    def bottom_anchors(cls) -> tuple["AnchorPoint", ...]:
        return (cls.BOTTOM_LEFT, cls.BOTTOM_CENTER, cls.BOTTOM_RIGHT)