captionbob.effects.progressive_opacity

Progressive opacity effect: each word is dim until it is spoken.

A caption shows a few words on one box, and it shows them all from its start. The first word has its full color. Each later word is dim until the time at which it is spoken. Then it turns to its full color, and it keeps that color until the caption goes.

A caption is one event of the script. libass draws one box behind the whole event, around all its lines, so this code measures no text. The box has square corners. It is as wide as the text and as high as its text lines, plus the stroke width and the paddings. 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/progressive_opacity.py

Settings

The command line and the HTTP API call this effect the style progressive_opacity. Its settings class is ProgressiveOpacitySettings. 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.
dim_opacity	number	0.25	Strength of a word that is not yet spoken, from 0 for a word that is not seen to 1 for the full color. The letters and the stroke of the word have this strength.
background_color	string	"#000000"	Color of the box behind the caption, as "#RRGGBB".
background_opacity	number	1.0	Strength of the box, from 0 for no box to 1 for a box that hides the video behind it.
background_side_padding	number	14.0	Room in pixels between the stroke of the text and the left and the right edge of the box.
background_vertical_padding	number	4.0	Room in pixels between the stroke of the text lines and the top and the bottom edge of the box. A text line is as high as the font size. With the two paddings at 0 the box is as large as the text lines plus the stroke.
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.

ProgressiveOpacitySettings

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

The look and the timing of the progressive opacity 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. In this effect the bottom position is the bottom of the caption text, and the box reaches below it by the stroke width and the vertical padding. The box reaches into the side margins by the stroke width and the side padding.

Args:

• dim_opacity: Strength of a word that is not yet spoken, from 0 for a word that is not seen to 1 for the full color. The letters and the stroke of the word have this strength.
• background_color: Color of the box behind the caption, as "#RRGGBB".
• background_opacity: Strength of the box, from 0 for no box to 1 for a box that hides the video behind it.
• background_side_padding: Room in pixels between the stroke of the text and the left and the right edge of the box.
• background_vertical_padding: Room in pixels between the stroke of the text lines and the top and the bottom edge of the box. A text line is as high as the font size. With the two paddings at 0 the box is as large as the text lines plus the stroke.
• 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 a color is not in the form "#RRGGBB", or when the font name is empty or holds a comma.

ProgressiveOpacitySettings.style_line

def style_line(self, margin_vertical: int) -> str

Write the ASS style line of these settings.

The style has the background border style, so libass draws one box behind each event. The events set the color, the transparency and the paddings of their box with tags.

Args:

• margin_vertical: Room in pixels between the bottom of the caption text and the bottom edge of the video.

Returns:

The style line of the captions.

Raises:

• ValueError: When the font name, the font size, a color, the stroke width or a margin is outside its range.

ProgressiveOpacityEffect

class ProgressiveOpacityEffect
    def __init__(self, settings: ProgressiveOpacitySettings) -> None

Builds the ASS script that turns each word full when it is spoken.

Args:

• settings: The look and the timing of the effect.

ProgressiveOpacityEffect.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. 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.