captionbob.effects.flare

Flare effect: bold white capitals and an orange-red spoken word.

A caption ends at the end of a sentence and, by default, at each other end mark, such as a comma. It shows its words in capitals with their end marks. A caption that ends with an end mark stays on one line, and so does a short caption. A longer caption has two lines, and the top line has the larger half of the words.

Each line has its own events, so that the second line sits the line step below the first. Each line has two events on two layers. The event on the outline layer draws the letters in the stroke color, with a border that reaches past the spread of the letters by the stroke width and fades out at its edge. The event on the text layer draws the white letters, each with a white border of the letter spread, which makes them heavier.

The word that is spoken turns orange-red, with its spread, for the time in which it is spoken. A caption appears at once with its first word and goes at once.

Source file: captionbob/effects/flare.py

Settings

The command line and the HTTP API call this effect the style flare. Its settings class is FlareSettings. 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	"Ubuntu"	Name of the font of the text.
font_size	integer	76	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.675	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.
capitals	boolean	true	True to write the words in capitals.
letter_width	number	0.86	The width of the letters as a part of the width that the font gives them, above 0.
letter_spread	number	2.5	How far the letters spread past the shapes of the font, in pixels. Each letter has an outline of its own color this wide, which makes it heavier. 0 gives the letters of the font.
outline_blur	number	1.5	How far the edge of the stroke fades out, in pixels. 0 gives a sharp edge.
line_letters	integer	11	The most letters, with the spaces, of a caption with no end mark at its end that stays on one line, 1 or above.
line_step	number	83.0	The room from the top of the first line to the top of the second line, in pixels, above 0.
spoken_color	string	"#E04E2D"	The color of the word that is spoken, as "#RRGGBB".
end_at_marks	boolean	true	True to end a caption at each end mark, such as a comma. A caption always ends at the end of a sentence.
hold_seconds	number	0.15	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

FlareSettings

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

The look and the timing of the flare effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. The primary color is the color of the letters. The stroke is the outline in the stroke color past the spread of the letters. The bottom position is the bottom of the first row of a caption. These settings follow them.

Args:

• capitals: True to write the words in capitals.
• letter_width: The width of the letters as a part of the width that the font gives them, above 0.
• letter_spread: How far the letters spread past the shapes of the font, in pixels. Each letter has an outline of its own color this wide, which makes it heavier. 0 gives the letters of the font.
• outline_blur: How far the edge of the stroke fades out, in pixels. 0 gives a sharp edge.
• line_letters: The most letters, with the spaces, of a caption with no end mark at its end that stays on one line, 1 or above.
• line_step: The room from the top of the first line to the top of the second line, in pixels, above 0.
• spoken_color: The color of the word that is spoken, as "#RRGGBB".
• end_at_marks: True to end a caption at each end mark, such as a comma. A caption always ends 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.

FlareEffect

class FlareEffect
    def __init__(self, settings: FlareSettings) -> None

Builds the ASS script of the flare effect.

Args:

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

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