captionbob.effects.clara

Clara effect: small white bold phrases in one or two lines.

Each caption shows a short phrase in small white bold letters, in the case in which it is spoken and with its end marks, such as commas and full stops. The letters have no outline and no shadow. A caption ends at the end of a sentence and, by default, also after each word with an end mark, such as a comma. A caption that has more words than one line holds is cut into lines with even word counts. A caption shows at once when its first word starts, and it goes at once.

The top line of a caption stays at one place: its bottom sits at the bottom position. Each line below it sits one line height lower. Each line is an event of its own, so that the line height is a setting and not the height of the font. Each line is placed by the top middle of its text. A line that is too wide for the room between the side margins breaks into more rows, and they grow down from the top of the line.

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

The defaults are the look of the source video of the effect, measured on its frames and scaled to a video of 1080x1920.

Source file: captionbob/effects/clara.py

Settings

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

Setting	Type	Default	Description
most_words	integer	6	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	"Ubuntu"	Name of the font of the text.
font_size	integer	63	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	0.0	Width of the outline in pixels. 0 gives no outline.
bottom_position	number	0.647	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.
letter_width	number	1.08	The width of the letters as a part of the width that the font gives them.
most_line_words	integer	5	The most words in one line. A caption with more words is cut into the fewest lines that hold them, with even word counts. A line at the top holds one word more than a line below it when the words do not divide evenly.
line_height	number	70.0	The rows from the bottom of one line of a caption to the bottom of the line below it.
phrase_breaks	boolean	true	True to end a caption after each word that ends with an end mark, such as a comma, and not only at the end of a sentence.
hold_seconds	number	0.3	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

ClaraSettings

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

The look and the timing of the clara 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 place of the bottom of the top line of a caption.

Args:

• letter_width: The width of the letters as a part of the width that the font gives them.
• most_line_words: The most words in one line. A caption with more words is cut into the fewest lines that hold them, with even word counts. A line at the top holds one word more than a line below it when the words do not divide evenly.
• line_height: The rows from the bottom of one line of a caption to the bottom of the line below it.
• phrase_breaks: True to end a caption after each word that ends with an end mark, such as a comma, and not only at the end of a sentence.
• 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.

ClaraEffect

class ClaraEffect
    def __init__(self, settings: ClaraSettings) -> None

Builds the ASS script of small white bold phrases in one or two lines.

Args:

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

ClaraEffect.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 line of a caption is one event, from the top line down, with the times of the caption. An event starts with the first word of its caption. 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.