captionbob.effects.zoom_in

Zoom in effect: a caption fades in small and grows to its full size.

A caption shows a few words. All its words show together from the time at which the first word is spoken. The parts of the time of a caption follow the old effect. In the first part the caption fades in at its start scale. In the next part it grows in a straight line to its full size. Then it stays, and in the last part it fades out. The outline fades and grows with the letters. While the caption grows, its top stays at one row and it stays in the middle of the video across.

A smaller caption would fit in fewer rows, so libass must break no line by itself. The effect asks the caption measure where libass breaks each caption at its full size, and it writes these breaks into the script.

The effect draws nothing itself. It builds the text of an ASS script, and the ffmpeg filter ass draws the script on the video. The common part of the effects is in effect_common.py.

Source file: captionbob/effects/zoom_in.py

Settings

The command line and the HTTP API call this effect the style zoom_in. Its settings class is ZoomInSettings. Each setting has the default below.

Setting	Type	Default	Description
most_words	integer	3	The most words that one caption shows.
fewest_words	integer	1	The fewest words that one caption shows, when its sentence is long enough for that.
font_name	string	"DejaVu Sans"	Name of the font of the text.
font_size	integer	80	Height of the font in pixels.
bold	boolean	true	True for bold text.
primary_color	string	"#FFFFFF"	Color of the text, as "#RRGGBB".
stroke_color	string	"#000000"	Color of the outline of the text, as "#RRGGBB".
stroke_width	number	6.0	Width of the outline in pixels. 0 gives no outline.
bottom_position	number	0.75	Where the bottom of the caption sits, as a part of the video height from the top. 0.75 is three quarters of the way down.
side_margin	integer	54	Room in pixels that stays free on the left and on the right of the caption. A caption that is too wide for the room between the margins breaks into lines.
start_scale	number	0.25	The size of a caption in the fade in part, as a part of its full size, above 0. 1 gives a caption that does not grow.
fade_in_part	number	0.25	The part of the time of a caption, at its start, in which it fades in at its start scale, from 0 to 1. 0 gives no fade in.
zoom_part	number	0.45	The part of the time of a caption, after the fade in part, in which it grows to its full size, from 0 to 1. 0 gives a caption that jumps to its full size at the end of the fade in part.
fade_out_part	number	0.1	The part of the time of a caption, at its end, in which it fades out, from 0 to 1. 0 gives no fade out. The three parts together are at most 1.
hold_seconds	number	0.6	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

ZoomInSettings

@dataclass(frozen=True)
class ZoomInSettings(CaptionSettings)

The look and the timing of the zoom in effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. These settings follow them. The bottom position is the bottom of a caption at its full size.

Args:

• start_scale: The size of a caption in the fade in part, as a part of its full size, above 0. 1 gives a caption that does not grow.
• fade_in_part: The part of the time of a caption, at its start, in which it fades in at its start scale, from 0 to 1. 0 gives no fade in.
• zoom_part: The part of the time of a caption, after the fade in part, in which it grows to its full size, from 0 to 1. 0 gives a caption that jumps to its full size at the end of the fade in part.
• fade_out_part: The part of the time of a caption, at its end, in which it fades out, from 0 to 1. 0 gives no fade out. The three parts together are at most 1.
• hold_seconds: The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

Raises:

• TypeError: When a word count is not a whole number.
• ValueError: When a value is outside its range, when the three parts together are above 1, when a color is not in the form "#RRGGBB", or when the font name is empty or holds a comma.

ZoomInEffect

class ZoomInEffect
    def __init__(
            self, settings: ZoomInSettings,
            caption_measure: CaptionMeasure) -> None

Builds the ASS script that fades each caption in small and grows it.

Args:

• settings: The look and the timing of the effect.
• caption_measure: The measure that says where libass breaks each caption into lines. It must use the ffmpeg that draws the video.

ZoomInEffect.build_ass_text

def build_ass_text(self, words: Sequence[Word], video: VideoInfo) -> str

Build the ASS script of the effect for the words of one video.

Each caption group is one event of the script. An event starts with its first word, and all its words show from that time. It ends when the next caption starts, and at the latest the hold time after its last word and at the end of the video.

Args:

• words: The words of the video in time order, each with its times.
• video: The frame size and the duration of the video.

Returns:

The text of the ASS script. It has no event when there are no words.

Raises:

• ValueError: When the side margins leave no room for the caption in the width of the video, or when libass draws no pixel for a word.
• RuntimeError: When the ffmpeg of the caption measure fails.